Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

Editing Tools

  • 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 don’t 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.

Table 1. AsciiDoc Editors
Capability GitHub Atom VS Code

Edit multiple files at once

–

✓

✓

Vale integration

–

🌟🌟

🌟🌟🌟

Java IDE

–

🌟

🌟🌟

TypeScript IDE

–

🌟🌟

🌟🌟🌟

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

    edit on github preview
    Edit on GitHub

    Note the limitations of the preview.

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

    edit on github propose
    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 pull request 1
    Edit on GitHub

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

    edit on github pull request 2
    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:

  • Style sheet for the documentation site isn’t applied and hence emphasis and other custom formatting isn’t shown in the preview

  • Conditional directives don’t work, because attributes aren’t defined, and hence text intended only for web isn’t shown at all in the preview

  • Macros don’t work, for example menu selection macros

  • Cross-references don’t 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 doesn’t break any formatting.

Atom Editor

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

atom editor
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:

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

  • Style sheet for the documentation site isn’t applied and hence emphasis and other custom formatting isn’t shown in the preview

  • Some macros don’t work

  • Cross-references don’t 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.

See the Vale documentation for instructions on installing it on macOS, Windows, or Linux.

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

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

Vale in VS Code
Using Vale in VS Code

1D5FF345-19F2-4F7B-836F-DA92F3CCD3F6