oliverdavies.uk/content/node.2d05cfa9-d5cf-41df-ba50-2c55b776f1f5.json

{
    "uuid": [
        {
            "value": "2d05cfa9-d5cf-41df-ba50-2c55b776f1f5"
        }
    ],
    "langcode": [
        {
            "value": "en"
        }
    ],
    "type": [
        {
            "target_id": "daily_email",
            "target_type": "node_type",
            "target_uuid": "8bde1f2f-eef9-4f2d-ae9c-96921f8193d7"
        }
    ],
    "revision_timestamp": [
        {
            "value": "2025-05-11T09:00:08+00:00"
        }
    ],
    "revision_uid": [
        {
            "target_type": "user",
            "target_uuid": "b8966985-d4b2-42a7-a319-2e94ccfbb849"
        }
    ],
    "revision_log": [],
    "status": [
        {
            "value": true
        }
    ],
    "uid": [
        {
            "target_type": "user",
            "target_uuid": "b8966985-d4b2-42a7-a319-2e94ccfbb849"
        }
    ],
    "title": [
        {
            "value": "Mermaid - markdown for charts"
        }
    ],
    "created": [
        {
            "value": "2024-08-18T00:00:00+00:00"
        }
    ],
    "changed": [
        {
            "value": "2025-05-11T09:00:08+00:00"
        }
    ],
    "promote": [
        {
            "value": false
        }
    ],
    "sticky": [
        {
            "value": false
        }
    ],
    "default_langcode": [
        {
            "value": true
        }
    ],
    "revision_translation_affected": [
        {
            "value": true
        }
    ],
    "path": [
        {
            "alias": "\/daily\/2024\/08\/18\/mermaid-markdown-for-charts",
            "langcode": "en"
        }
    ],
    "body": [
        {
            "value": "\n          <p><a href=\"\/daily\/2024\/08\/16\/what-are-err--req-and-res\">Whilst mentoring at the School of Code Hackathon<\/a>, something the team and I discussed was documentation and documenting any decisions we made about the approaches they were taking, the techologies to use, etc.<\/p>\n\n<p>We kept it simple by adding this to a README file, but I also mentioned <a href=\"\/daily\/2022\/09\/23\/adrs-technical-design-documents\">ADRs and technical decision documents<\/a> and how they can be written in Markdown and stored alongside the code in the same repository.<\/p>\n\n<p>Another approach to documentation that I like is to create diagrams and flow charts.<\/p>\n\n<p>I've used various tools to do this, but recently, I've started to use <a href=\"https:\/\/github.com\/mermaid-js\/mermaid\">Mermaid<\/a>, which is a Markdown-like syntax to generate charts and diagrams.<\/p>\n\n<h2 id=\"here%27s-the-thing\">Here's the thing<\/h2>\n\n<p>There are online tools to do this, but there's also <code>mmdc<\/code> command-line tool that generates diagrams locally.<\/p>\n\n<p>This means that I can easily generate diagrams and store in the codebase too, and have them version-controlled so I can see the history as they evolve during the project.<\/p>\n\n<h2 id=\"want-an-example%3F\">Want an example?<\/h2>\n\n<p><a href=\"https:\/\/github.com\/opdavies\/build-configs\/blob\/f02fce7ff5b5cff202ec8b893a4b3c7e7c56f3c4\/docs\/diagram.mmd\">Here's one I did for the Build Configs tool<\/a>, which I recently open-sourced, and that GitHub renders by default (you can click the 'Code' tab to see the code for the chart).<\/p>\n\n        ",
            "format": "full_html",
            "processed": "\n          <p><a href=\"http:\/\/default\/daily\/2024\/08\/16\/what-are-err--req-and-res\">Whilst mentoring at the School of Code Hackathon<\/a>, something the team and I discussed was documentation and documenting any decisions we made about the approaches they were taking, the techologies to use, etc.<\/p>\n\n<p>We kept it simple by adding this to a README file, but I also mentioned <a href=\"http:\/\/default\/daily\/2022\/09\/23\/adrs-technical-design-documents\">ADRs and technical decision documents<\/a> and how they can be written in Markdown and stored alongside the code in the same repository.<\/p>\n\n<p>Another approach to documentation that I like is to create diagrams and flow charts.<\/p>\n\n<p>I've used various tools to do this, but recently, I've started to use <a href=\"https:\/\/github.com\/mermaid-js\/mermaid\">Mermaid<\/a>, which is a Markdown-like syntax to generate charts and diagrams.<\/p>\n\n<h2 id=\"here%27s-the-thing\">Here's the thing<\/h2>\n\n<p>There are online tools to do this, but there's also <code>mmdc<\/code> command-line tool that generates diagrams locally.<\/p>\n\n<p>This means that I can easily generate diagrams and store in the codebase too, and have them version-controlled so I can see the history as they evolve during the project.<\/p>\n\n<h2 id=\"want-an-example%3F\">Want an example?<\/h2>\n\n<p><a href=\"https:\/\/github.com\/opdavies\/build-configs\/blob\/f02fce7ff5b5cff202ec8b893a4b3c7e7c56f3c4\/docs\/diagram.mmd\">Here's one I did for the Build Configs tool<\/a>, which I recently open-sourced, and that GitHub renders by default (you can click the 'Code' tab to see the code for the chart).<\/p>\n\n        ",
            "summary": null
        }
    ]
}