Writing Tools

To write Vaadin documentation, you need the following:

• Git

• An editor to edit AsciiDoc

• Java and/or TypeScript IDE (optional)

• Vale linter (optional)

A Java or TypeScript IDE is needed if you need to edit code examples.

The Vale linter makes various language and style checks. GitHub runs Vale when you make a pull request in the Vaadin Docs repository, so you do not necessarily need it, but running it locally shortens your feedback loop. Using Vale locally while writing makes this process more convenient. You can run Vale command-line and some editors have Vale integration.

Editors and IDEs

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

You could also use an IDE such as Eclipse, IntelliJ IDEA, or NetBeans. They all have good support for Java development, but TypeScript and AsciiDoc support varies. They may or may not have a suitable plugin for their support.

Editing on GitHub

You can make small fixes to documentation in GitHub itself. It is only recommended for small fixes, as the preview process is slow.

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 using the Preview tab in the GitHub editor.

   

   

   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.

   

   

   Revise commit title and description for pull request

   You can also give an extended description.

   Click Propose file change

4. Review the change and click Create pull request

   

   

   Edit on GitHub

5. Revise the title of the commit for the pull request.

   

   

   Revise commit title and description for pull request

   You can also give the extended description here. GitHub shows it in the discussion of the pull request.

See Submitting Documentation for more details about making a pull request at GitHub.

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

The Atom text editor has decent support for editing and previewing AsciiDoc files.

Editing AsciiDoc in Atom

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:

   Show code

   Expand code

    $ 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.

Vale

Vale is a natural language linter that supports AsciiDoc, among other formats. Checks for many of the Vaadin style guidelines are included in the custom Vale rules. GitHub runs the checks automatically when you make a pull request for documentation.

Please see Vale documentation for instructions on installing it on macOS, Windows, or Linux.

You can run it on command-line simply by giving one or more AsciiDoc files as parameters:

Show code

Expand code

$ vale editing-tools.asciidoc
 editing-tools.asciidoc
 154:32  warning  'simply' is a weasel word.      Vaadin.Weasel
✖ 0 errors, 1 warnings and 0 suggestions in 1 file.

A Vale integration plugin is available for at least Atom (atomic-vale) and VS Code (Vale + VS Code).

Using Vale in VS Code