Contributing to Documentation

Instructions and guidelines for contributing to the official Vaadin documentation — this website.

Edit in GitHub
Edit Locally
Visual Studio Code
Writing Style Guidelines

The Vaadin documentation is maintained in GitHub, written using AsciiDoc, and built using Design System Publisher.

The main branches in the repository are latest for the latest version of Vaadin, and hilla for the Hilla documentation.

To learn how to write with AsciiDoc authoring syntax, including all of the extensions in Design System Publisher, see the Design System Publisher documentation. You should also familiarize yourself with the writing style guidelines.

Edit in GitHub

You can make small corrections or suggestions to the documentation by clicking the Edit this page on GitHub link at the end of any page. It opens that page for editing in GitHub — you’ll need a GitHub account. There you can edit the content and later submit a pull request. For external contributors, a fork of the repository is created on your own GitHub account.

The GitHub editor is good for small edits, but not for writing new pages or large sections. The preview rendering on GitHub doesn’t show the content the same as the official documentation website. This is because Design System Publisher has custom extensions and styling. To see an exact preview of a page you’re editing, you’ll need to run the development server, locally.

Edit Locally

To edit and preview locally the documentation website on your computer, do the following steps:

First, clone the repository. For example, you would execute the following from the command-line:
```
git clone https://github.com/vaadin/docs
```
Next, start Design System Publisher by entering the following in the docs folder:
```
cd docs
npm run dspublisher:start
```
You need a commercial Vaadin subscription to run Design System Publisher. Once the development server is up and running, the website should open up in your browser on http://localhost:8000.

Visual Studio Code

For a nicer writing experience, install AsciiDoctor and Vale together with the Vale extension. Vale helps you to conform to the documentation writing guidelines, making the PR review process faster.

AsciiDoc Settings

When editing an AsciiDoc file in Visual Studio Code, you might get the following error annotation on the main heading or title of all pages:

level 0 sections can only be used when doctype is book

Add the following snippet to your VS Code settings.json file to avoid this:

{
    // ...
    "asciidoc.preview.asciidoctorAttributes": {
        "doctype": "book"
    },
    // ...
}

Writing Style Guidelines

Vale: Vale helps contributors to follow the writing style rules and guidelines that are specific to the Vaadin and Hilla documentation.
Style Guide: Writing style guidelines for documentation writers.
Word List: List of words and phrases to avoid, and word usage advice for the Vaadin documentation.