This guide is for authors of Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors. For general markup syntax, see General Guide to Writing Documentation.
HTML and Open Graph Metadata#
All documents must have an
html_meta directive at the top of every page.
When rendered to HTML, it inserts
<meta> tags for improved search engine results and nicer social media posts.
Authors should include at least
keywords meta tags.
The following is an example of
Note that the content of the two tags
property=og:description should be identical.
--- html_meta: "description": "Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." "property=og:description": "Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." "property=og:title": "Authors Guide" "keywords": "Plone, Documentation, SEO, meta, spellcheck, linkcheck, lexer" ---
This renders in the HTML
<head> section as follows.
<meta content="Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." name="description" /> <meta content="Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." property="og:description" /> <meta content="Authors Guide" property="og:title" /> <meta content="Plone, Documentation, SEO, meta, spellcheck, linkcheck, lexer" name="keywords" />
Additional Open Graph metadata is implemented through the Sphinx extension
sphinxext-opengraph and the MyST
html_meta directive, which resolves to the Docutils
See the site-wide configuration in
We strive for high quality documentation, setting the following minimum standards.
Markup syntax must be valid#
See both the specific markup syntax above and general markup in General Guide to Writing Documentation.
To validate markup, run the following command.
/_build/html/index.html in a web browser.
American English Spelling, Grammar, and Syntax#
Spellings are enforced through
We use the locale
Spelling is configured in
Authors should add new words and proper names using correct casing to
docs/spelling_wordlist.txt, sorted alphabetically.
To validate spelling, run the following command.
/_build/spellcheck/ for misspellings.
Because it is difficult to automate good English grammar and syntax, we do not strictly enforce it. We also understand that contributors might not be fluent in English. We encourage contributors to make a reasonable effort, and to seek help from community members who are fluent in English. When you submit a pull request, please select a Reviewer to review your work.
Pygments provides syntax highlighting in Sphinx.
When including code snippets, you should specify the language. Authors must use a proper Pygments lexer and not generate warnings.
The snippet must be valid syntax for the language you specify, else it will not be highlighted properly. Avoid adding comments to code snippets, unless you use valid comment syntax for that language. For example, JSON does not allow comments.
Do not indicate elided or omitted code with ellipses (
These are almost never valid syntax and will cause syntax highlighting to fail for the code block.
Choosing a Lexer#
Some lexers are less than perfect.
If your code block does not highlight well, then consider specifying a less ambitious lexer, such as
shell for commands to be issued in a terminal session.
Do not include shell prompts.
This will make commands easy to copy and paste for readers.
console for output of a shell session.
If you have a mix of a shell command and its output, then use
xml does not work well, then try
jsx has a complex syntax that is difficult to parse.
We have high hopes for the project
We include it in our
Please contribute to its further development.
less are also suboptimal and particular.
If no other lexer works well, then fall back to
At least then the build will succeed without warnings, although syntax highlighting for such snippets will not appear.
Validate the Lexer#
Always build the page to validate syntax. The change should not be merged if there are any Sphinx warnings. The Sphinx console will display any warnings, such as the following.
/Plone/documentation/classic-ui/bodyclasses.md:10: WARNING: Could not lex literal_block as "python". Highlighting skipped.
The above warning indicates that the syntax is not valid. Common mistakes include:
…to indicate omitted code. It is preferable to never use ellipses. If you must do that, comment it out using the language's comment syntax.
Using comments in JSON.
A previous code block bleeds through to the next due to invalid MyST syntax.
To validate code block syntax, run the following command.
When using the online lexer, if any red-bordered rectangles appear, then the lexer for Pygments interprets your snippet as not valid. You can search the Pygments issue tracker for possible solutions, or submit a pull request to enhance the lexer.