Skip to content

Latest commit

 

History

History
64 lines (42 loc) · 3.9 KB

markdown-and-formatting.md

File metadata and controls

64 lines (42 loc) · 3.9 KB
Raw

Markdown and Formatting

The Basics

  • all content is in /content, the actual text of the guide is stored in /content/src.
    • /content/version.txt is autogenerated, the actual version is stored elsewhere
  • the project uses GitHub-flavored Markdown, because the web version of the guide is published to a github page (at https:patterns.sociocracy30.org)
  • for a new version of the guide to be published, the source first needs to be rendered with mdtoos

Styleguide

All Markdown files in this repository (including this one) use the following style

  • paragraphs are in a single line (use word wrap / soft wrap in the editor)
  • use one blank line between paragraps, two blank lines before a new header, and one blank line at the end of the file
  • avoid trailing spaces.
  • - (minus) for bulleted lists (with an indentation of 4 spaces, which is required for lists of 2 levels of indentation anyway)
  • _ (underscore) for emphasis and
  • ** for strong emphasis

Preview

When previewing edits with any Markdown preview, the following things will not be displayed correctly:

  • the contents of the <summary>-tag
  • internal links (to other sections of the guide, or to the glossary) will look like links, but they will not work, because the preprocessor replaces all links with the correct targets (or replaces the links entirely when output to PDF)
  • illustrations
  • definitions {{define:...}}

Links and Images

Links to other sections of the guide: [link text](section:section-name). Section name is the name of the file that is linked to, without any extension (html or md), and without any path

Links to other websites: `link text

Links where the URL should be visible <https://...>

The Glossary

The project glossary is defined in /content/glossary.yaml - the format is YAML 1.1, a simple explanation of the format can be found on Wikipedia or in the Ansible documentation

Example for a glossary entry:

  social-technology:
    name: Social Technology
    definition: "**Social technology** is any process, technique, method, skill or any other approach that people can use to influence social systems – organizations, societies, communities etc. – to support achieving shared objectives and guide meaningful interaction and exchange."
    glossary: Any process, technique, method, skill or any other approach that people can use to influence social systems – organizations, societies, communities etc. – to support achieving shared objectives and guide meaningful interaction and exchange.

Each term in the glossary is represented as as a dictionary with three keys

  • name: The name of the entry (title case)
  • definition: The text that will show up with the {{define...}} macro. This text typically starts with "A thing is", followed by the explanation.
  • glossary: The text that will show up in the glossary overlays and on the glossary page. This text is the explanation only.

The key for looking up a term's dictionary is the name of the term, in lowercase characters and with spaces replaced by dashes.

The glossary provides three things

  1. a macro for rendering a term's definition in a page: {{define:governance-backlog}}. This macro is used in a separate paragraph.
  2. glossary links, like [driver](glossary:driver). The link text can be anything, the target agter "glossary:" is the key for looking up the term in the glossary. The glossary link is rendered as an overlay in the web version, and currently discarded in the ebook versions (although that might change in a future version of mdtools)
  3. the glossary page that contains a list of all entries with explanations