Docs as code

This template repo can be used to author your technical documentation and slide decks in markdown, mermaid and/or PlantUML. Using the npm scripts you can generate diagrams as svg/png etc, output slide decks in html/pptx and push everything to confluence.

The repo uses and is entirely dependent on:

• Mermaid
• PlantUML
• Marp
• Markdown Confluence

Generate diagrams

To generate the PlantUML diagrams via docker, run:

npm run start
npm run generate

if using podman run:

npm run start-pod
npm run generate

This will start a container that is able to render the puml files into svg pictures.

note: the puml files must all be under the ./docs folder.

If you would like a live puml preview and use vscode, try the extension jebbs.plantuml with the following settings:

  "plantuml.server": "http://localhost:8088",
  "plantuml.render": "PlantUMLServer",
  "plantuml.exportOutDir": "docs",
  "plantuml.exportFormat": "svg",
  "plantuml.diagramsRoot": "docs",
  "plantuml.exportSubFolder": false,
  "plantuml.exportIncludeFolderHeirarchy": true,

Diagrams

Diagrams can be written in mermaid, PlantUML or GraphViz.

Mermaid is the simplest and can be added directly to markdown files like so:

flowchart TD
    write(Write mermaid) --> happy(Be happy)

Loading

PlantUML offers more diagram types and better rendering of C4 architecture diagrams. To create these, add a .puml file anywhere under the ./docs folder and follow the instructions above to generate. For a better authoring experience, install the PlantUML VSCode extension and syntax extension.

The vscode workspace settings to render live previews with the local PlantUML server (npm run start) are included in this repo.

Slide decks

If you need to produce slide decks, you can produce these using markdown with the excellent marp. Again, there is a VSCode extension to provide live previews.

To create a powerpoint deck for your markdown slide deck, add an npm script for your file, similar to generate:intro.

Publish to confluence

The contents of the docs folder can be pushed to confluence by running npm run publish.

They will be published under this parent page: https://eaflood.atlassian.net/wiki/spaces/FFG/pages/5411209331/Future+Farming+Grants+Technical+Documentation

You will need to specify a username and API key in a .env file. To do so, create an API token here then copy the .env.example file to a file called .env then fill out your atlassian username and API token.