e1ad692cb3
* contributing updates first draft * ran yarn prettier * updated links * removed test xref * Update contribute/documentation/README.md Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com> Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>
2.7 KiB
DELETE THIS LINE: If draft = false, then the document will not be built in the doc site. If the date is earlier than the build date, than the document will not show in the build site. Use these settings to control whether future content is shown in the doc site. +++ draft = "false" date = "yyyy-mm-dd" title = "Title in sentence case" description = "Description in title case" keywords = ["grafana", "enter", "keywords", "here"] type = "docs" [menu.docs] name = "Name of topic" identifier = "identifier" parent = "menu parent" weight = 100 +++
Reference
The reference topic type is for storing reference information, such as extensive tables, lists, or other information that is used as support for a task. Reference topics are also designed for API information.
Often reference topics are linked from task topics, because they contain information the user needs in order to perform a task.
Grafana CLI is one example of a reference topic.
Lists
Lists of commands or parameters are often organized in reference topics. The information you need to present will dictate the format.
- They might
- be in
- unordered lists.
Configuration is an example of lists.
Tables
If you have a large list of things to store in a table, then you are probably dealing with reference information. Hugo accepts either tables in Markdown or in HTML format, so use whichever is easier for you.
The Glossary provides an example of reference data in a table.
Empty markdown table
While you might not need a heading for each table, headings are a good way to chunk information if you have several tables. They also make the content easy to skim. Use headings or intro paragraphs like this one to explain to the reader what the information in the table is used for.
Empty HTML table
And here is intro text, similar to the paragraph in the previous section. Do not add local styling to the table. The website CSS will take care of that for you.
| Firstname | Lastname | Age |
|---|---|---|
| Jill | Smith | 50 |
| Eve | Jackson | 94 |
API documentation
API documentation is always a reference topic rather than a task topic, but it has its own rules.