Contributing to OctoMY™ documentation

This is a short cheat sheet for contributing to the user-facing documentation under content/doc/published/. Full conventions live in the style guide that ships with a built copy of OctoMY™.

Three rules

  1. Source is pure markdown. No YAML frontmatter, no /static/ URL prefix, no Jinja {% … %} block tags, and no links into the developer-only internal docs. The only templating allowed in the body is {{ context.config.get('org-name') }} for the project name and for hidden comments.

  2. Page metadata lives in a sidecar. Each <page>.md may have a co-located <page>.meta.yaml that carries the website styling, in-app behaviour, and globally-surfaced data (tags, prerequisites, …) for that page. The sidecar is split into three top-level blocks: website:, in_app:, and global:. Adding a key that is not in the schema is rejected by lint.

  3. Lint locally before pushing. Build the helpbuild tool once, then run it over the tree:

    helpbuild --input content/doc/published/ --lint --no-widget-manifest-check

    It will reject the most common authoring mistakes (stray frontmatter fences, /static/ links, links into internal docs, unknown sidecar keys) at the line where they happen.

What goes in which file

You want to … Edit this
Add a paragraph, fix a typo, restructure a section The page's <page>.md
Change which website wrapper / pre-/post-wrappers / Bootstrap badges show up The page's <page>.meta.yaml, under website:
Add prerequisites / related concepts / next-step links The page's <page>.meta.yaml, under global:
Change the in-app TOC label / sort order / search rank The page's <page>.meta.yaml, under in_app:
Add a brand-new image Drop the file under the page's images/ (or a shared published/images/... for cross-page assets), then reference it as ./images/foo.png or /images/shared/foo.png
Add a brand-new widget screenshot Use the widget: URL scheme (widget:ActivityOrbWidget?mode=offline) — the build pipeline renders these at deploy time and at runtime in-app

Where to look when something is wrong

  • helpbuild --lint output points at file:line: for every violation.
  • Schema for the sidecar: content/doc/publishing/page-meta.schema.json.
  • Full policy (for contributors who want the long version): see the developer documentation that ships with a built copy of OctoMY™.
In this section