To make sure the discourse post displays correctly when published to Vanilla website there are some important rules to follow.
Title of the post should be just a name of the component or pattern
The title of discourse post is going to be used as a title and heading in Vanilla documentation, so it should contain only the name of given component or pattern.
Don’t:
[Pattern] Search and Filter (spec)
Do:
Search and Filter
Don’t use first level of heading
The main heading (<h1>
) of the page is going to be based on the title of the post, any headings in the content should use h2, h3, etc.
Don’t:
# Introduction
This is some intro…
# Variants
## First variant
Description…
Do:
## Introduction
This is some intro…
## Variants
### First variant
Description…
Add proper descriptions to the images
By default when adding images to discourse posts the image description is based on a file name. This is usually not very user friendly. To improve accessibility of the images you should make sure to give proper descriptions of the image content.
Don’t:
![search_and_filter_hover](http://assets.ubuntu.com/...)
Do:
![Hover state of search and filter component](http://assets.ubuntu.com/...)