Skip to end of metadata
Go to start of metadata

Infusion documentation is written using Markdown and then converted to HTML using Docpad. The source files and templates are stored in github: https://github.com/fluid-project/infusion-docs/

Editorial

  • Any references to grade names, parameter names, function names, etc. should be styled as code, for example, use fluid.defaults and not fluid.defaults.
    • This applies inside narrative paragraphs, tables, etc.
    • DO NOT use code styling in headings; this will break links to the heading anchors.
  • References to HTML elements should be styled as code and wrapped in < >, for example, a <div> element.
  • Section headings should use sentence-style capitalization (only capitalize the first word and proper nouns) rather than headline-style capitalization.
  • Code snippets should use line breaks judiciously, to improve readability and avoid horizontal scrolling.

Page structure

  • Pages should begin with introductory paragraph(s) without any <h2> level header. Subsequent sections should begin with <h2> headers.
    • The page title, specified in the metadata of the Markdown file, will be converted to an <h1> header ahead of the introductory content.
  • Any text that will be consistent across a number of pages (e.g. production status notes or deprecation warnings) should NOT be hard-coded into the Markdown. Instead, use metadata that will be processed by Docpad, to ensure consistent wordings.
    • The specific mechanism for this will be determined when it needs to be implemented.
  • "Notes" should be wrapped in <div> elements with the infusion-docs-note class and begin with "Note:"; This will ensure that the note is styled according to the designs.

Questions

  1. Should text in a header be styled as code? It makes detecting a header a little bit difficult.
  2. Should this style guide live inside the github repository with the source files, or here in the Fluid wiki space?
  • No labels