Documentation

Documentation versions (currently viewingVaadin 23)
New Acceleration Kits: Observability Kit, SSO Kit, and Swing Kit. Read the blog post.

Editing Content

The articles/components folder contains folders representing the website’s top-level sections (1). Each page within a top-level section has its own sub-folder (2), and an index.asciidoc file (3) containing the page’s main content. Pages can be divided into multiple tabs by AsciiDoc files (4) for each tab. Top-level sections can have their own index pages represented by index.asciidoc files in the section’s root folder (5).

└── articles
    └── ds
        └── components              (1)
            ├── accordion           (2)
            │   ├── index.asciidoc  (3)
            │   └── api.asciidoc    (4)
            ⋮
            └── index.asciidoc      (5)

For example, the above structure corresponds to an Accordion page in the Components section, containing Usage and API tabs:

Documentation page with "Usage" and "API" tabs
A tabbed page

Whenever changes to a page’s contents are saved, Publisher rebuilds the page and automatically refresh the page after a couple of seconds.

Page Metadata

Each AsciiDoc file starts with a YAML formatted metadata block (called the “front matter”), defined between lines with three dashes (---). The following properties can be defined in this block:

title (string)

The page’s title as shown in the navigation tree, breadcrumbs, search results and, for tabbed pages, in the page header. The title displayed for non-tabbed pages is defined with the page title heading.

layout (string, optional)

Page layout. Set to tabbed-page for pages containing multiple tabs.

tab-title (string, optional)

The title displayed for the tab in pages containing multiple tabs.

page-links (string[], optional)

Links to be displayed in the page header. Can be used for linking, for example, to the component repository, Figma file, or other resources.

order (number, optional)

Overrides the default placement of the page in the navigation tree.

Example front matter block
---
title: Accordion
layout: tabbed-page
tab-title: Usage
page-links:
  - https://github.com/vaadin/vaadin-flow-components/releases/tag/23.3.0.alpha3[Flow 23.3.0.alpha3]
  - https://github.com/vaadin/vaadin-accordion/releases/tag/v23.3.0-beta1[Web Component 23.3.0-beta1]
---

= Accordion  // <- title displayed on the page itself

Adding Pages

New pages are added by creating a new AsciiDoc file in the desired folder. To add a new component page, create a folder inside articles/components, add a new index.asciidoc file inside it, and configure its metadata.

Files starting with an underscore, for example articles/components/_shared.asciidoc, are considered as “partials” to be included by other files, and won’t appear as their own page on the website.

It takes a few seconds for Publisher to add the new page to the navigation tree, after which the page refreshes automatically. You need to refresh the browser to use the updated search index.

Page Content Syntax

The AsciiDoctor site has a handy quick reference for the AsciiDoc format.

Table 1. Common AsciiDoc formatting syntax
= Page Title

Page Title

== Level 1 Section Title

Level 1 Section Title

=== Level 2 Section Title

Level 2 Section Title

==== Level 3 Section Title

Level 3 Section Title

*bold text*

bold text

_italic text_

italic text

`monospace text`

monospace text

#highlighted text#

highlighted text

 https://example.com[A hyperlink]
<<../path/to/folder#, Link to another folder's index page>>
<<../path/to/folder/page#, Link to another page>>
<<../path/to/folder/page#section, Link to another page's section>>
* Bullet list item
** Nested bullet list item
  • Bullet list item

    • Nested bullet list item

. Numbered list item
.. Nested numbered list item
  1. Numbered list item

    1. Nested numbered list item

* [ ] Checkbox, unchecked
* [x] Checkbox, checked
  • ❏ Checkbox, unchecked

  • ✓ Checkbox, checked

image::path/to/image.png[Alt text]
Alt text

Images are automatically scaled and optimized (excluding SVG images) for the production build.

Other common features include:

6DF51E1C-15BB-4E15-A3C7-5C616B7BFC35