mirror of
https://github.com/Cacti/documentation.git
synced 2026-11-01 17:51:12 +09:00
142 lines
4.8 KiB
Markdown
142 lines
4.8 KiB
Markdown
# Documentation Standards
|
|
|
|
Write instructions that match the Cacti branch being documented. State when a
|
|
feature is available only on the development branch or in a particular release.
|
|
Verify commands, configuration names, links, and screenshots against that
|
|
version. Keep changes focused on the affected topic.
|
|
|
|
## Source and corrections
|
|
|
|
This manual is maintained in the
|
|
[Cacti documentation repository](https://github.com/Cacti/documentation).
|
|
Submit corrections there, linking an existing issue when applicable. Use
|
|
`develop` unless maintainers request a maintenance branch. A repository change
|
|
reaches the public website through the project's build and deployment process.
|
|
|
|
## Markdown format
|
|
|
|
The repository's `.mdlrc` loads `.mdl_style.rb`. These files define the local
|
|
Markdown checks. Preserve the existing page's style where it does not conflict
|
|
with those checks.
|
|
|
|
### Titles
|
|
|
|
Use ATX headings with a space after the hash characters. Use one level-one
|
|
heading for the page title, then organize sections with levels two through five.
|
|
Use level six for numbered example, figure, or table captions when needed.
|
|
Avoid punctuation at the end of headings and keep heading text descriptive.
|
|
|
|
```markdown
|
|
# Page title
|
|
|
|
## Main section
|
|
|
|
### Subsection
|
|
|
|
Paragraph text.
|
|
```
|
|
|
|
Separate headings from surrounding content with a blank line. Preserve existing
|
|
heading anchors when possible; when renaming a heading, update links to it.
|
|
Empty HTML anchors may preserve public fragment links when headings move or
|
|
change. Use Markdown for visible links and ordinary page content.
|
|
|
|
### Text and lists
|
|
|
|
Wrap prose at 79 characters. Leave one blank line between paragraphs and around
|
|
lists and code blocks. Do not leave trailing whitespace or repeated blank
|
|
lines. Do not use raw HTML for ordinary page content.
|
|
|
|
Use `-` for unordered lists, a number followed by a full stop for ordered lists,
|
|
and consistent indentation for nested items and continuation text.
|
|
|
|
```markdown
|
|
- First item.
|
|
- Second item with a continuation that remains part of the same list item.
|
|
|
|
1. First step.
|
|
2. Second step.
|
|
```
|
|
|
|
Use backticks for file paths, commands, configuration keys, and literal values.
|
|
Use bold text for interface labels where it improves readability.
|
|
|
|
### Code blocks
|
|
|
|
Use fenced code blocks with a language label such as `console`, `bash`, `php`,
|
|
`sql`, or `ini`. Keep example commands reproducible and identify placeholders.
|
|
Use continuation lines for long commands where the shell supports them. Code
|
|
and table widths are exempt from the prose line-length rule in the current
|
|
style configuration.
|
|
|
|
Do not include real credentials, tokens, private keys, or unredacted logs.
|
|
Explain required privileges and commands that alter or delete stored data.
|
|
|
|
### Links and images
|
|
|
|
Use Markdown links with meaningful labels. Use relative `.md` paths for manual
|
|
pages so the links work in the repository and published manual.
|
|
|
|
```markdown
|
|
[Data Collectors](Data-Collectors.md)
|
|
[Collection settings](Settings-Poller.md#general-settings)
|
|
|
|
```
|
|
|
|
Check that target files and heading anchors exist. Add new guides to
|
|
`Manual-Index.md` and link entry pages from `README.md`. Check image filenames
|
|
and use alternate text that describes the image. Explain when a screenshot
|
|
shows an older interface or a specific theme.
|
|
|
|
### Tables
|
|
|
|
Use Markdown tables with a header and separator row. Keep column names and
|
|
units explicit. Add a caption when the table needs to be referenced elsewhere.
|
|
|
|
## Copyright
|
|
|
|
End pages with a separator and the Cacti Group copyright notice, following the
|
|
target branch's current year:
|
|
|
|
```markdown
|
|
---
|
|
|
|
Copyright (c) 2004-2026 The Cacti Group
|
|
```
|
|
|
|
## Validate changes
|
|
|
|
Install Ruby and the `mdl` gem, then run checks from the documentation root:
|
|
|
|
```console
|
|
gem install mdl
|
|
bin/check_markdown_style.sh Changed-Page.md
|
|
bin/check_missing_link.sh
|
|
```
|
|
|
|
Omit the filename to run the Markdown check across the repository. Existing
|
|
files may have unrelated lint failures; distinguish those from failures added
|
|
by the change. `check_missing_link.sh` checks whether Markdown filenames occur
|
|
in `README.md`; it does not validate every link target or heading anchor.
|
|
Check those separately.
|
|
|
|
The repository's GitHub Actions spelling workflow installs the pinned
|
|
requirements from `.github/codespell-requirements.txt`. To run the same spelling
|
|
check in a Python virtual environment:
|
|
|
|
```console
|
|
python3 -m venv /tmp/cacti-docs-spelling
|
|
/tmp/cacti-docs-spelling/bin/python -m pip install \
|
|
--only-binary :all: --require-hashes \
|
|
-r .github/codespell-requirements.txt
|
|
/tmp/cacti-docs-spelling/bin/codespell --config .codespell.cfg
|
|
```
|
|
|
|
Review `git diff --check` and the rendered Markdown before submitting. Verify
|
|
that commands and menus describe the intended version; passing Markdown and
|
|
spelling checks does not establish technical accuracy.
|
|
|
|
---
|
|
|
|
Copyright (c) 2004-2026 The Cacti Group
|