You are viewing documentation for Vaadin Framework 8 and related products View documentation for Vaadin Framework 7 ›
Editing Tools · Vaadin
Contributing - Editing Tools
 Edit This Page

Editing Tools

Marko Grönroos, Vaadin Ltd.

You can use any editor to edit AsciiDoc. However, some editors support code highlighting and integrated preview. For others, you need to use external preview.

You minimally need to enable the experimental and web attributes. Applying the stylesheet allows previewing emphasis and some other styling.

Editing on GitHub

On any page of the vaadin.com/docs documentation site, you can click on the Edit This Page button to edit the contents.

Editing and Previewing

  1. Edit the page source

  2. Please preview your modifications carefully using the Preview tab in the GitHub editor.

    edit on github preview
    Figure 1. Edit on GitHub

    Note the limitations of the preview.

  3. Give the file change a title (in the Propose file change section). Please make it descriptive.

    edit on github propose
    Figure 2. Revise commit title and description for pull request

    You can also give an extended description, which is shown in GitHub.

    Click Propose file change

  4. Review the change and click Create pull request

    edit on github pull request 1
    Figure 3. Edit on GitHub
  5. Revise the title of the commit for the pull request.

    edit on github pull request 2
    Figure 4. Revise commit title and description for pull request

    You can also give the extended description here. It will be shown in pull request discussion.

The maintainer then feds the request through our code review just like any other commit.

Limitations

While handy for small fixes, editing on GitHub has several limitations:

  • Stylesheet for the documentation site is not applied and hence emphasis and other custom formatting is not shown in the preview

  • Conditional directives do not work, because attributes are not defined, and hence text intended only for web is not shown at all in the preview

  • Macros do not work, for example menu selection macros

  • Cross-references do not point to correct paths in the preview

  • Some formatting is wrong due to differences in the AsciiDoc compiler used in GitHub

Hence, this method is only recommended for trivial fixes where you can be certain that the contribution does not break any formatting.

Atom Editor

We recommend using the Atom text editor to edit and preview AsciiDoc files.

atom editor

Installing and Configuring AsciiDoc Plug-ins

  1. You can install the Atom from the atom.io website or with a package manager in your operating system.

  2. Then, you need to install the AsciiDoc preview and highlighting plug-ins with the Atom Package Manager as follows:

    $ apm install asciidoc-preview language-asciidoc
  3. In the Atom preferences, for the AsciiDoc plugin, you need to have the following attributes enabled:

    experimental web
  4. Now, when editing an AsciiDoc file, press Ctrl+Shift+A to preview the file.

Limitations

While Atom is a nice editor to work with and previewing is quick, it has several limitations:

  • Stylesheet for the documentation site is not applied and hence emphasis and other custom formatting is not shown in the preview

  • Some macros do not work

  • Cross-references do not point to correct paths in the preview

  • Some formatting is wrong due to differences in the AsciiDoc version used in the AsciiDoc plugin for Atom.

Hence, even if you do most editing work with Atom, you must preview by building the website, as described in [workflow].

Compiling AsciiDoc Command-Line

To compile a single file command-line with AsciiDoctor, you need to install AsciiDoctor and get the asciidoc.css stylesheet from the documentation site repository to view emphasis markup, etc.

Installing

Ruby and RubyGems are needed to run AsciiDoctor. For example, in Ubuntu (RubyGems is included in Ruby):

# apt-get install ruby

Then, you can install the AsciiDoctor gem. Also, Coderay is needed for rendering code excerpts.

# gem install asciidoctor coderay

Basic Use

$ asciidoctor -a stylesheet=asciidoc.css -a \
  stylesdir=<path>/vaadin-docs/website/public/css \
  -a experimental -a web myarticle.asciidoc

The <path> is the location where you cloned the documentation site repository. The command compiles the file to the current directory.

Note that the above command requires the asciidoc.css stylesheet.

Browser Plugins for Firefox, Chrome, or Opera

See github.com/asciidoctor for the plugins

  • No AsciiDoctor installation is required

  • The plugins do not apply the stylesheet

Other Live Preview

For other tools and external live preview, see Editing AsciiDoc with Live Preview.