This repository contains the source of XOD documentation which is served at https://xod.io/docs/
All content sources are under ./docs
directory. Each subdirectory (and the
root ./docs
as well) correspond to a single page on https://xod.io/docs/. If a
user requests https://xod.io/docs/foo/bar/
the system looks for a
./docs/foo/bar/README.md
file.
The README.md
is an entry point for each page. It’s a file written in
Markdown
syntax so that the authors can
focus on content rather than on layout issues. Nevertheless, README.md
may
include raw HTML and Handlebars template mixins for cases when a page is hard to
write in plain Markdown. As you might expect, README.md
may also refer to
images and other asset files located next to it.
Pages can contain translations to other languages. README.md
holds the English
version whereas nearby DE.md
, IT.md
, RU.md
, etc hold its translations. The
site chooses its source depending on the language drop-down selection falling
back to English if no translation is found for a particular page.
See Analog sensors guide for an example.
Some pages like the Supported Hardware present highly structured data (see how it renders on xod.io) which would be hard to maintain using plain Markdown/HTML.
In such cases, a YAML file to hold the data can be created. The structured object described in it is available to the Markdown source with a little template magic:
{{#each index}}
<h2>{{ section }}</h2>
{{#each parts}}
<div>
{{ part }} {{ kind }} {{#if vendor}}by {{ vendor }}{{/if}}.
</div>
{{/each}}
{{/each}}
Note the {{ xxx }}
placeholders. They are
Handlebars template tags. Any .yaml
file put next
to README.md
is available by its basename for templating (index
for
index.yaml
in the example
above).
To keep all source files consistent and easy to maintain several formatting rules apply. Notably, all Markdown files should be word-wrapped to be no wider than 80 characters.
Instead of describing all the rules and checking them on review, they are
enforced automatically using Prettier. If you have done
a significant portion of work, run yarn prettier
to format your Markdown
correctly.
One thing you’ll see in Markdown sources is a block at the very top fenced with
---
. This is metadata used by the site engine:
---
title: Hello World
version: 1.2.3
---
The title
field is passed to a browser to render the page’s <title/>
.
The version
is a semver of the current page content
used to understand whether a translation lags behind the master version or not.
An increment in the patch part (3
) denotes typo fixes and wording improvements
which require no translation updates. A bump of minor part (2
) denotes
additions and refinements which are desirable to see in translated versions. A
change in the major part (1
) denotes a total rewrite. If the version
field
is absent, it is implied to be 1.0.0
.
$ yarn prettier:all
# Format *all* Markdown in the repo
$ yarn prettier README.md CONTRIBUTING.md
# Format only files specified
$ yarn prettier-check:all
# Dry-check all Markdown in the repo
All content is available under a Creative Commons license.
Any help with fixing the grammar, translating, resolving ambiguities, adding references, and general improvement is much appreciated. Refer to CONTRIBUTING.md to learn how.