Introduction
Every site you deliver, and every custom extension you build, could need a manual: which page types there are, what each field does, how a plugin or module works, where to find the news items. Usually that is a Word or PDF file that gets mailed once at launch, ends up in someone's downloads folder and is out of date after the first change. With this extension the manual is a Markdown file in the sitepackage or the custom extension, right next to the code it describes, and editors open it from their dashboard.
What it does
- Always at hand
- A dashboard widget shows the introduction and the chapters; one click opens the full manual inside the backend. No searching through mail or intranet, no separate login.
- Easy to look things up
- A table of contents next to the text that stays in view, optional chapter numbers (1., 1.1) and sections, and a marker that shows where you are, like the selected page in the page tree.
- Kept up to date with the site
- The manual is a file in git. Change a content element and update its chapter in the same commit; it is reviewed and deployed together with the code, so the manual never lags behind.
- Written in plain Markdown
- Headings, lists, tables, links and screenshots. It previews in your IDE and on GitHub or Bitbucket, and the same file can feed a Word export for the client's archive.
- On paper too
- A print button prints the manual or saves it as PDF, without the backend around it, each chapter on a new page.
- The right manual for the right people
- One widget per manual, so access is granted per backend group with the core setting Allowed dashboard widgets. A manual for editors and one for administrators is two widgets.
- For sitepackages and custom extensions
- Any extension can ship its own manual: the sitepackage for the site as a whole, a custom extension for its own plugin, module or records. The manual travels with the extension, so it is there on every site that installs it.
- Safe by design
- The request never chooses a file, raw HTML in the Markdown is stripped, and
images are only served from
Resources/.Public - Fits the backend
- Core styles and tokens, light and dark backend, keyboard and screen reader friendly; English, Dutch and German labels.
Screenshots
The widget on the dashboard, with the introduction and the chapters.
The full view, with chapters and sections in the table of contents and the current section marked.
Both show the example manual Documentation/Example/EditorManual.md from the repository, registered with numbered and contentsDepth: 2.