Contributing to Documentation

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

Edit in GitHub
Edit Locally
Visual Studio Code
Page Meta Data
Writing Style Guidelines

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

The main branch in the repository is latest for the latest version of Vaadin. Older versions have their own branches.

To learn how to write with AsciiDoc authoring syntax, including all 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"
    },
    // ...
}

Page Meta Data

Each AsciiDoc file starts with a YAML formatted metadata block called the "front matter", defined between lines with three dashes. The front matter attributes for meta title and meta description are defined in this block. These attributes are page-title and meta-description.

When suggesting changes or additions to an article, make sure it includes both attributes and that they follow the recommendations listed below.

You can find a list of all front matter attributes in the Design System Publisher documentation. For Vaadin documentation, the attributes listed here override the title and description as the page’s meta tags.

Meta Title

A page’s title is shown as the browser tab’s title, search results and social media share previews. This attribute should convey the primary topic of the page:

Includes the keyword, Vaadin;
Has a length from fifty to sixty characters;
Uses | as a divider; and
Starts with "How to" whenever it’s fitting.

Below is an example that uses these suggestions:

page-title: How to contribute to Vaadin Documentation.

Meta Description

The description of a page is shown in search results and social media share previews. It should summarize what the page is about:

Includes the keyword, Vaadin; and
Has a maximum length from one-hundred fifty to one-hundred sixty characters.

Below is an example of this:

meta-description: Learn how you can contribute to the official Vaadin documentation
by reading the contribution instructions and guidelines.

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.

Docs