ace Documentation

Ace (Ajax.org Cloud9 Editor)

27,145 stars JavaScript JavaScript 1 file · ~7,155 tokens
RAW Doc

File: Readme.md

Ace (Ajax.org Cloud9 Editor)


Note: The new site at http://ace.c9.io contains all the info below along with an embedding guide and all the other resources you need to get started with Ace.

Ace is a standalone code editor written in JavaScript. Our goal is to create a browser based editor that matches and extends the features, usability and performance of existing native editors such as TextMate, Vim or Eclipse. It can be easily embedded in any web page or JavaScript application. Ace is developed as the primary editor for Cloud9 IDE and the successor of the Mozilla Skywriter (Bespin) Project.

Features

  • Syntax highlighting for over 120 languages (TextMate/Sublime/.tmlanguage files can be imported)
  • Over 20 themes (TextMate/Sublime/.tmtheme files can be imported)
  • Automatic indent and outdent
  • An optional command line
  • Handles huge documents (at last check, 4,000,000 lines is the upper limit)
  • Fully customizable key bindings including vim and Emacs modes
  • Search and replace with regular expressions
  • Highlight matching parentheses
  • Toggle between soft tabs and real tabs
  • Displays hidden characters
  • Drag and drop text using the mouse
  • Line wrapping
  • Code folding
  • Multiple cursors and selections
  • Live syntax checker (currently JavaScript/CoffeeScript/CSS/XQuery)
  • Full language client support for many languages available via ace-linters
  • Cut, copy, and paste functionality

Take Ace for a spin!

Check out the Ace live demo or get a Cloud9 IDE account to experience Ace while editing one of your own GitHub projects.

If you want, you can use Ace as a textarea replacement thanks to the Ace Bookmarklet.

Embedding Ace

Ace can be easily embedded into any existing web page. You can either use one of pre-packaged versions of ace (just copy one of src* subdirectories somewhere into your project), or use requireJS to load contents of lib/ace as ace

The easiest version is simply:

html
some text
<script src="src/ace.js" type="text/javascript" charset="utf-8"></script>
<script>
    var editor = ace.edit("editor");
</script>

Exploring configuration options Configuring-Ace

With "editor" being the id of the DOM element, which should be converted to an editor. Note that this element must be explicitly sized and positioned absolute or relative for Ace to work. e.g.

css
#editor {
    position: absolute;
    width: 500px;
    height: 400px;
}

To change the theme simply include the Theme's JavaScript file

html
<script src="src/theme-twilight.js" type="text/javascript" charset="utf-8"></script>

and configure the editor to use the theme:

javascript
editor.setTheme("ace/theme/twilight");

By default the editor only supports plain text mode; many other languages are available as separate modules. After including the mode's JavaScript file:

html
<script src="src/mode-javascript.js" type="text/javascript" charset="utf-8"></script>

The mode can then be used like this:

javascript
var JavaScriptMode = ace.require("ace/mode/javascript").Mode;
editor.session.setMode(new JavaScriptMode());

to destroy editor use

javascript
editor.destroy();
editor.container.remove();

Documentation

Additional usage information, including events to listen to and extending syntax highlighters, can be found on the main Ace website.

You can also find API documentation at https://ajaxorg.github.io/ace-api-docs/.

Also check out the sample code for the kitchen sink demo app.

If you still need help, feel free to ask a question on our discussions page.

Running Ace

After the checkout Ace works out of the box. No build step is required. To try it out, simply start the bundled mini HTTP server using Node.JS

bash
node ./static.js

The editor can then be opened at http://localhost:8888/kitchen-sink.html.

To open the editor with a file:/// URL see the wiki.

Building Ace

You do not generally need to build ACE. The ace-builds repository endeavours to maintain the latest build, and you can just copy one of src* subdirectories somewhere into your project.

However, all you need is Node.js and npm installed to package ACE. Just run npm install in the ace folder to install dependencies:

bash
npm install
node ./Makefile.dryice.js

To package Ace, we use the dryice build tool developed by the Mozilla Skywriter team. Call node Makefile.dryice.js on the command-line to start the packing. This build script accepts the following options

bash
-m                 minify build files with uglify-js          
-nc                namespace require and define calls with "ace"
-bm                builds the bookmarklet version
--target ./path    specify relative path for output folder (default value is "./build")

To generate all the files in the ace-builds repository, run node Makefile.dryice.js full --target ../ace-builds

Running the Unit Tests

The Ace unit tests can run on node.js. Assuming you have already done npm install, just call:

bash
npm run test

You can also run the tests in your browser by serving:

text
http://localhost:8888/src/test/tests.html

This makes debugging failing tests much easier.

Contributing

Ace is a community project and wouldn't be what it is without contributions! We actively encourage and support contributions. The Ace source code is released under the BSD License. This license is very simple, and is friendly to all kinds of projects, whether open source or not. Take charge of your editor and add your favorite language highlighting and keybindings!

Feel free to fork and improve/enhance Ace any way you want. If you feel that the editor or the Ace community will benefit from your changes, please open a pull request. For more information on our contributing guidelines, see CONTRIBUTING.md.

File: demo/kitchen-sink/docs/markdown.md

Ace (Ajax.org Cloud9 Editor)

Ace is a standalone code editor written in JavaScript. Our goal is to create a browser based editor that matches and extends the features, usability and performance of existing native editors such as TextMate, Vim or Eclipse. It can be easily embedded in any web page or JavaScript application. Ace is developed as the primary editor for Cloud9 IDE and the successor of the Mozilla Skywriter (Bespin) Project.

Features

  • Syntax highlighting
  • Automatic indent and outdent
  • An optional command line
  • Handles huge documents (100,000 lines and more are no problem)
  • Fully customizable key bindings including VI and Emacs modes
  • Themes (TextMate themes can be imported)
  • Search and replace with regular expressions
  • Highlight matching parentheses
  • Toggle between soft tabs and real tabs
  • Displays hidden characters
  • Drag and drop text using the mouse
  • Line wrapping
  • Unstructured / user code folding
  • Live syntax checker (currently JavaScript/CoffeeScript)

Take Ace for a spin!

Check out the Ace live demo or get a Cloud9 IDE account to experience Ace while editing one of your own GitHub projects.

If you want, you can use Ace as a textarea replacement thanks to the Ace Bookmarklet.

History

Previously known as “Bespin” and “Skywriter” it’s now known as Ace (Ajax.org Cloud9 Editor)! Bespin and Ace started as two independent projects, both aiming to build a no-compromise code editor component for the web. Bespin started as part of Mozilla Labs and was based on the canvas tag, while Ace is the Editor component of the Cloud9 IDE and is using the DOM for rendering. After the release of Ace at JSConf.eu 2010 in Berlin the Skywriter team decided to merge Ace with a simplified version of Skywriter's plugin system and some of Skywriter's extensibility points. All these changes have been merged back to Ace. Both Ajax.org and Mozilla are actively developing and maintaining Ace.

Getting the code

Ace is a community project. We actively encourage and support contributions. The Ace source code is hosted on GitHub. It is released under the BSD License. This license is very simple, and is friendly to all kinds of projects, whether open source or not. Take charge of your editor and add your favorite language highlighting and keybindings!

bash
git clone git://github.com/ajaxorg/ace.git
    cd ace
    git submodule update --init --recursive

Embedding Ace

Ace can be easily embedded into any existing web page. The Ace git repository ships with a pre-packaged version of Ace inside of the build directory. The same packaged files are also available as a separate download. Simply copy the contents of the src subdirectory somewhere into your project and take a look at the included demos of how to use Ace.

The easiest version is simply:

html
some text
    <script src="src/ace.js" type="text/javascript" charset="utf-8"></script>
    <script>
    window.onload = function() {
        var editor = ace.edit("editor");
    };
    </script>

With "editor" being the id of the DOM element, which should be converted to an editor. Note that this element must be explicitly sized and positioned absolute or relative for Ace to work. e.g.

css
#editor {
        position: absolute;
        width: 500px;
        height: 400px;
    }

To change the theme simply include the Theme's JavaScript file

html
<script src="src/theme-twilight.js" type="text/javascript" charset="utf-8"></script>

and configure the editor to use the theme:

javascript
editor.setTheme("ace/theme/twilight");

By default the editor only supports plain text mode; many other languages are available as separate modules. After including the mode's JavaScript file:

html
<script src="src/mode-javascript.js" type="text/javascript" charset="utf-8"></script>

Then the mode can be used like this:

javascript
var JavaScriptMode = require("ace/mode/javascript").Mode;
    editor.getSession().setMode(new JavaScriptMode());

Documentation

You find a lot more sample code in the demo app.

There is also some documentation on the wiki page.

If you still need help, feel free to drop a mail on the ace mailing list.

Running Ace

After the checkout Ace works out of the box. No build step is required. Open 'editor.html' in any browser except Google Chrome. Google Chrome doesn't allow XMLHTTPRequests from files loaded from disc (i.e. with a file:/// URL). To open Ace in Chrome simply start the bundled mini HTTP server:

bash
./static.py

Or using Node.JS

bash
./static.js

The editor can then be opened at http://localhost:8888/index.html.

Package Ace

To package Ace we use the dryice build tool developed by the Mozilla Skywriter team. Before you can build you need to make sure that the submodules are up to date.

bash
git submodule update --init --recursive

Afterwards Ace can be built by calling

bash
./Makefile.dryice.js normal

The packaged Ace will be put in the 'build' folder.

To build the bookmarklet version execute

bash
./Makefile.dryice.js bm

Running the Unit Tests

The Ace unit tests run on node.js. Before the first run a couple of node modules have to be installed. The easiest way to do this is by using the node package manager (npm). In the Ace base directory simply call

bash
npm link .

To run the tests call:

bash
node lib/ace/test/all.js

You can also run the tests in your browser by serving:

text
http://localhost:8888/lib/ace/test/tests.html

This makes debugging failing tests way more easier.

Contributing

Ace wouldn't be what it is without contributions! Feel free to fork and improve/enhance Ace any way you want. If you feel that the editor or the Ace community will benefit from your changes, please open a pull request. To protect the interests of the Ace contributors and users we require contributors to sign a Contributors License Agreement (CLA) before we pull the changes into the main repository. Our CLA is the simplest of agreements, requiring that the contributions you make to an ajax.org project are only those you're allowed to make. This helps us significantly reduce future legal risk for everyone involved. It is easy, helps everyone, takes ten minutes, and only needs to be completed once. There are two versions of the agreement:

  1. The Individual CLA: use this version if you're working on an ajax.org in your spare time, or can clearly claim ownership of copyright in what you'll be submitting.
  2. The Corporate CLA: have your corporate lawyer review and submit this if your company is going to be contributing to ajax.org projects

If you want to contribute to an ajax.org project please print the CLA and fill it out and sign it. Then either send it by snail mail or fax to us or send it back scanned (or as a photo) by email.

Email: [email protected]

Fax: +31 (0) 206388953

Address: Ajax.org B.V.
Keizersgracht 241
1016 EA, Amsterdam
the Netherlands

File: demo/kitchen-sink/docs/rst.rst

========================================== *reStructuredText* Highlighter for **Ace**

.. seealso::

http://docutils.sourceforge.net/docs/user/rst/quickstart.html

ReStructuredText Primer

:Author: Richard Jones
:Version: $Revision: 5801 $
:Copyright: This document has been placed in the public domain.

.. contents::

The text below contains links that look like "(quickref__)". These
are relative links that point to the Quick reStructuredText_ user
reference. If these links don't work, please refer to the master quick reference_ document.

__
.. _Quick reStructuredText: quickref.html
.. _master quick reference:
http://docutils.sourceforge.net/docs/user/rst/quickref.html

.. Note:: This document is an informal introduction to
reStructuredText. The What Next?_ section below has links to
further resources, including a formal reference.

Structure

From the outset, let me say that "Structured Text" is probably a bit
of a misnomer. It's more like "Relaxed Text" that uses certain
consistent patterns. These patterns are interpreted by a HTML
converter to produce "Very Structured Text" that can be used by a web
browser.

The most basic pattern recognised is a paragraph (quickref__).
That's a chunk of text that is separated by blank lines (one is
enough). Paragraphs must have the same indentation -- that is, line
up at their left edge. Paragraphs that start indented will result in
indented quote paragraphs. For example::

This is a paragraph. It's quite
short.

text
This paragraph will result in an indented block of
 text, typically used for quoting other text.

This is another one.

Results in:

This is a paragraph. It's quite
short.

text
This paragraph will result in an indented block of
 text, typically used for quoting other text.

This is another one.

__ quickref.html#paragraphs

Text styles

(quickref__)

__ quickref.html#inline-markup

Inside paragraphs and other bodies of text, you may additionally mark
text for italics with "*italics*" or bold with
"**bold**". This is called "inline markup".

If you want something to appear as a fixed-space literal, use
"double back-quotes". Note that no further fiddling is done
inside the double back-quotes -- so asterisks "*" etc. are left
alone.

If you find that you want to use one of the "special" characters in
text, it will generally be OK -- reStructuredText is pretty smart.
For example, this lone asterisk * is handled just fine, as is the
asterisk in this equation: 56=30. If you actually
want text *surrounded by asterisks to not be italicised, then
you need to indicate that the asterisk is not special. You do this by
placing a backslash just before it, like so "\*" (quickref__), or
by enclosing it in double back-quotes (inline literals), like this::

text
``*``

__ quickref.html#escaping

.. Tip:: Think of inline markup as a form of (parentheses) and use it
the same way: immediately before and after the text being marked
up. Inline markup by itself (surrounded by whitespace) or in the
middle of a word won't be recognized. See the markup spec__ for
full details.

__ ../../ref/rst/restructuredtext.html#inline-markup

Lists

Lists of items come in three main flavours: enumerated,
bulleted and definitions. In all list cases, you may have as
many paragraphs, sublists, etc. as you want, as long as the left-hand
side of the paragraph or whatever aligns with the first line of text
in the list item.

Lists must always start a new paragraph -- that is, they must appear
after a blank line.

enumerated lists (numbers, letters or roman numerals; quickref__)
__ quickref.html#enumerated-lists

Start a line off with a number or letter followed by a period ".",
right bracket ")" or surrounded by brackets "( )" -- whatever you're
comfortable with. All of the following forms are recognised::

  1. numbers

A. upper-case letters
and it goes over many lines

text
with two paragraphs and all!

a. lower-case letters

text
3. with a sub-list starting at a different number
 4. make sure the numbers are in the correct sequence though!

I. upper-case roman numerals

i. lower-case roman numerals

(1) numbers again

  1. and again

Results in (note: the different enumerated list styles are not
always supported by every web browser, so you may not get the full
effect here):

  1. numbers

A. upper-case letters
and it goes over many lines

with two paragraphs and all!

a. lower-case letters

  1. with a sub-list starting at a different number
  2. make sure the numbers are in the correct sequence though!

I. upper-case roman numerals

i. lower-case roman numerals

(1) numbers again

  1. and again

bulleted lists (quickref__)
__ quickref.html#bullet-lists

Just like enumerated lists, start the line off with a bullet point
character - either "-", "+" or "*"::

  • a bullet point using "*"

    • a sub-list using "-"

      • yet another sub-list

    • another item

Results in:

  • a bullet point using "*"

    • a sub-list using "-"

      • yet another sub-list

    • another item

definition lists (quickref__)
__ quickref.html#definition-lists

Unlike the other two, the definition lists consist of a term, and
the definition of that term. The format of a definition list is::

what
Definition lists associate a term with a definition.

how
The term is a one-line phrase, and the definition is one or more
paragraphs or body elements, indented relative to the term.
Blank lines are not allowed between term and definition.

Results in:

what
Definition lists associate a term with a definition.

how
The term is a one-line phrase, and the definition is one or more
paragraphs or body elements, indented relative to the term.
Blank lines are not allowed between term and definition.

Preformatting (code samples)

(quickref__)

__ quickref.html#literal-blocks

To just include a chunk of preformatted, never-to-be-fiddled-with
text, finish the prior paragraph with "::". The preformatted
block is finished when the text falls back to the same indentation
level as a paragraph prior to the preformatted block. For example::

An example::

text
Whitespace, newlines, blank lines, and all kinds of markup
    (like *this* or \this) is preserved by literal blocks.
Lookie here, I've dropped an indentation level
(but not far enough)

no more example

Results in:

An example::

text
Whitespace, newlines, blank lines, and all kinds of markup
  (like *this* or \this) is preserved by literal blocks.

Lookie here, I've dropped an indentation level
(but not far enough)

no more example

Note that if a paragraph consists only of "::", then it's removed
from the output::

::

text
This is preformatted text, and the
  last "::" paragraph is removed

Results in:

::

text
This is preformatted text, and the
last "::" paragraph is removed

Sections

(quickref__)

__ quickref.html#section-structure

To break longer text up into sections, you use section headers.
These are a single line of text (one or more words) with adornment: an
underline alone, or an underline and an overline together, in dashes
"-----", equals "======", tildes "~~~~~~" or any of the
non-alphanumeric characters = - ` : ' " ~ ^ _ * + # < > that you
feel comfortable with. An underline-only adornment is distinct from
an overline-and-underline adornment using the same character. The
underline/overline must be at least as long as the title text. Be
consistent, since all sections marked with the same adornment style
are deemed to be at the same level::

Chapter 1 Title

Section 1.1 Title

Subsection 1.1.1 Title

text
Section 1.2 Title
  -----------------

  Chapter 2 Title
  ===============

This results in the following structure, illustrated by simplified
pseudo-XML::

    <section>
        <title>
            Chapter 1 Title
        <section>
            <title>
                Section 1.1 Title
            <section>
                <title>
                    Subsection 1.1.1 Title
        <section>
            <title>
                Section 1.2 Title
    <section>
        <title>
            Chapter 2 Title

(Pseudo-XML uses indentation for nesting and has no end-tags.  It's
not possible to show actual processed output, as in the other
examples, because sections cannot exist inside block quotes.  For a
concrete example, compare the section structure of this document's
source text and processed output.)

Note that section headers are available as link targets, just using
their name.  To link to the Lists_ heading, I write "``Lists_``".  If
the heading has a space in it like `text styles`_, we need to quote
the heading "```text styles`_``".


Document Title / Subtitle
`````````````````````````

The title of the whole document is distinct from section titles and
may be formatted somewhat differently (e.g. the HTML writer by default
shows it as a centered heading).

To indicate the document title in reStructuredText, use a unique adornment
style at the beginning of the document.  To indicate the document subtitle,
use another unique adornment style immediately after the document title.  For
example::

    ================
     Document Title
    ================
    ----------
     Subtitle
    ----------

    Section Title
    =============

    ...

Note that "Document Title" and "Section Title" above both use equals
signs, but are distict and unrelated styles.  The text of
overline-and-underlined titles (but not underlined-only) may be inset
for aesthetics.


Images
------

(quickref__)

__ quickref.html#directives

To include an image in your document, you use the the ``image`` directive__.
For example::

  .. image:: images/biohazard.png

results in:

.. image:: images/biohazard.png

The ``images/biohazard.png`` part indicates the filename of the image
you wish to appear in the document. There's no restriction placed on
the image (format, size etc).  If the image is to appear in HTML and
you wish to supply additional information, you may::

  .. image:: images/biohazard.png
     :height: 100
     :width: 200
     :scale: 50
     :alt: alternate text

See the full `image directive documentation`__ for more info.

__ ../../ref/rst/directives.html
__ ../../ref/rst/directives.html#images


What Next?
----------

This primer introduces the most common features of reStructuredText,
but there are a lot more to explore.  The `Quick reStructuredText`_
user reference is a good place to go next.  For complete details, the
`reStructuredText Markup Specification`_ is the place to go [#]_.

Users who have questions or need assistance with Docutils or
reStructuredText should post a message to the Docutils-users_ mailing
list.

.. [#] If that relative link doesn't work, try the master document:
   http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.

.. _reStructuredText Markup Specification:
   ../../ref/rst/restructuredtext.html
.. _Docutils-users: ../mailing-lists.html#docutils-users
.. _Docutils project web site: http://docutils.sourceforge.net/

---

## File: doc/index.md

# Ace API Reference

Welcome to the Ace API Reference Guide. Ace is a standalone code editor written in JavaScript that you can embed onto any website. We're used in a bunch of places already, like GitHub, Google, and Facebook.

On the left, you'll find a list of all of our currently documented classes. There are plenty more to do, but these represent the "core" set. For more information on how to work with Ace, check out the [main Ace website](https://ace.c9.io).

---

## File: doc/README.md

# Introduction

The API doc build takes a look a source Javascript files in the _lib_ directory, and turns it into HTML output in the _api_ directory. It uses [Panino](https://github.com/gjtorikian/panino-docs) to perform the conversion.

For any questions on the build system, please see that repo.

# Building

In the root directory, just run:

    make doc

In this directory, just run:

    npm install
    node build.js

---

## File: lib/ace/mode/xquery/Readme.md

This files are build from [xqlint](https://github.com/wcandillon/xqlint) (using the `grunt ace_build`)

---

## File: src/mode/_test/Readme.md

`tokens_<modeName>.json` files keep information about correct tokens and tokenizer states for all modes supported by ace.
They are generated from `text_<modeName>.txt` or `demo/kitchen-sink/docs/*` with

```sh
node highlight_rules_test.js -gen
```

command.

---

## File: tool/Readme.md

Helper Scripts for Ace
======================

To use this you need to install node.js. and run `npm install` in this directory.


# add_mode.js

  Run 
```
node add_mode.js ModeName "extension1|extension2|^FullName"
```
  to create all the files needed for a new mode named `ModeName` 
  this adds stubs for:
    `ace/mode/mode_name.js`
    `ace/mode/mode_name_hightlight_rules.js`
    `ace/snippets/mode_name.js`
    `ace/demo/kitchen_sink/docs/mode_name.extension1`
  and adds entry for the new mode to `ace/ext/modelist.js`
 
 
# tmlanguage.js

```
node tmlanguage.js ./templates/dummy.JSON-tmLanguage
```

# update_deps.js
To update `jshint` to new version:
1. Clone last version from https://github.com/jshint/jshint
2. Replace all `lodash` with `underscore` in requires in `jshint/src/*.js`
3. Add `_.slice = require("lodash.slice");` to `src/scope-manager.js` after `var _ = ...`
4. Add `_.clone = require("lodash.clone");` to `src/jshint.js` after `var _ = ...`
5. Add ```  
   "underscore": latest
   "lodash.clone": "^4.5.0",
   "lodash.slice": "^4.2.0"
   ``` to `package.json`, remove `lodash` and run `npm i`
6. Change in `ace/tool/update_deps.js` jshint path `deps.jshint.browserify.path` with your path to changed jshint
7. Run `node update_deps.js jshint`

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →