Writing Tools

• Git

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

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.

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 documentation site, you can click on the Edit This Page button to edit the contents.

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

   

   Edit on GitHub

   Note the 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.

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

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

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

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

Editing AsciiDoc in Atom

1. You can install the Atom from the 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

3. In the Atom preferences, for the AsciiDoc plugin, you need to have the following attributes enabled:

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

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

Hence, even if you do most editing work with Atom, you must preview by building the website.

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

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

Using Vale in VS Code