{"id":18445693,"url":"https://github.com/voronenko/runbooks-mkdocs","last_synced_at":"2025-04-08T00:31:41.055Z","repository":{"id":38430448,"uuid":"251278774","full_name":"Voronenko/runbooks-mkdocs","owner":"Voronenko","description":"Template repository aiming creation of the runbooks combined with basic lightweight documentation portal based on mkdocs, plantuml diagrams, and set of selected plugins","archived":false,"fork":false,"pushed_at":"2022-12-09T04:31:51.000Z","size":16619,"stargazers_count":4,"open_issues_count":4,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-23T03:08:10.184Z","etag":null,"topics":["mkdocs","project-documentation","runbooks"],"latest_commit_sha":null,"homepage":"https://voronenko.github.io/runbooks-mkdocs","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Voronenko.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-30T11:01:04.000Z","updated_at":"2024-08-07T18:33:36.000Z","dependencies_parsed_at":"2023-01-25T16:16:16.896Z","dependency_job_id":null,"html_url":"https://github.com/Voronenko/runbooks-mkdocs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voronenko%2Frunbooks-mkdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voronenko%2Frunbooks-mkdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voronenko%2Frunbooks-mkdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voronenko%2Frunbooks-mkdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Voronenko","download_url":"https://codeload.github.com/Voronenko/runbooks-mkdocs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247755341,"owners_count":20990616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mkdocs","project-documentation","runbooks"],"created_at":"2024-11-06T07:06:55.884Z","updated_at":"2025-04-08T00:31:39.598Z","avatar_url":"https://github.com/Voronenko.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Automatic publishing to gh-pages using github-actions\n\nWe will be using 3rd party action https://github.com/peaceiris/actions-gh-pages\n\nYou need to do once:\n\n```\nssh-keygen -t rsa -b 4096 -C \"$(git config user.email)\" -f gh-pages -N \"\"\n# You will get 2 files:\n#   gh-pages.pub (public key)\n#   gh-pages     (private key)\n```\n\nNext, Go to Repository Settings\n\nGo to Deploy Keys and add your public key with the Allow write access\nGo to Secrets and add your private key as ACTIONS_DEPLOY_KEY\n\nNow you can add fragment to your github workflow pipeline\n\n\n```yml\n\n      - name: Deploy\n        uses: peaceiris/actions-gh-pages@v3.6.1\n        with:\n          publish_dir: ./site\n          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}\n          publish_branch: gh-pages\n\n```\n\n## Automatic publishing to gitlab\n\nPlease find idea for automatic gitlab pages publishing on a pipeline below\n\n```yaml\nimage: python:3.9-buster\n# CD/CI example for gitlab\n# TODO: Introduce image with pre-built tools for easy run\nbefore_script:\n  - pip install -r requirements.txt\n  - DEBIAN_FRONTEND=noninteractive apt update\n  - DEBIAN_FRONTEND=noninteractive apt-get -yq install plantuml graphviz\n\ntest:\n  stage: test\n  script:\n  - mkdocs build --verbose --site-dir test\n  artifacts:\n    paths:\n    - test\n  except:\n  - master\n\npages:\n  stage: deploy\n  script:\n  - mkdocs build\n  artifacts:\n    paths:\n    - public\n    expire_in: 1 week\n  only:\n  - master\n```\n\n## Automatic publishing to confluence\n\nSo far, best working automated tool is  https://github.com/kovetskiy/mark, although it is not ideal\n\n# Extras\n\n# mkdocs-table-reader-plugin\n\n[MkDocs](https://www.mkdocs.org/) plugin that adds a `{{ read_csv('table.csv') }}` markdown tag to directly insert CSV files in a page.\n\nThis helps to enable building reproducible reports. For more complex use cases, consider [pheasant](https://pheasant.daizutabi.net/) or [nbconvert](https://tanbro.github.io/mkdocs-nbconvert/).\n\n## Setup\n\nInstall the plugin using `pip3`:\n\n```bash\npip3 install mkdocs-table-reader-plugin\n```\n\nNext, add the following lines to your `mkdocs.yml`:\n\n```yml\nplugins:\n  - search\n  - table-reader\n```\n\n\u003e If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set.\n\n## Usage\n\nIn your markdown documents you can now use:\n\n```html\n{{ read_csv('path_to_table.csv') }}\n```\n\nWhere the path is relative to the location of your project's `mkdocs.yml` file.\n\nUnder the hood this is basically:\n\n```python\nimport pandas as pd\ndf = pd.read_csv('path_to_table.csv')\ndf.to_markdown(showindex=False)\n```\n\nWhich means you can pass all parameters of [pandas.read_csv()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html).\n\n### Available readers\n\nThe table reader functions implemented from `pandas`:\n\n- `{{ read_csv() }}` passed to [pandas.read_csv()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html).\n- `{{ read_table() }}` passed to [pandas.read_table()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_table.html)`.\n- `{{ read_fwf() }}` passed to [pandas.read_fwf()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_fwf.html).\n- `{{ read_excel() }}` passed to [pandas.read_excel()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html).\n\n# Macros plugin\n\nhttps://github.com/fralau/mkdocs_macros_plugin\n```\npip install mkdocs-macros-plugin\n```\n\n```\n\nplugins:\n    - search\n    - macros\n\n```\n\n**mkdocs-macros-plugin** is a plugin that makes it easier for contributors\nof an [MkDocs](https://www.mkdocs.org/) website to produce richer and more beautiful pages. It transforms the markdown pages\ninto [jinja2](https://jinja.palletsprojects.com/en/2.10.x/) templates\nthat use **variables**, calls to **macros** and custom **filters**.\n\nRegular **variables** can be defined in four ways:\n\n  1. global (for designers of the website): in the `mkdocs.yml` file,\n    under the `extra` heading\n  1. global(for contributors): in external yaml definition files\n  1. global (for programmers): in a `main.py` file (Python),\n    by adding them to a dictionary\n  1. local (for contributors): in the markdown file, with a `{%set variable = value %}`\n statement\n\n\nSimilarly programmers can define **macros** and **filters**,\nas Python functions in the `main.py` file, which the users will then be able to\nuse without much difficulty, as jinja2 directives in the markdown page.\n\nYou can leverage the power of Python in markdown thanks to jinja2\nby writing this :\n\n```markdown\nThe unit price of product A is {{ unit_price }} EUR.\nTaking the standard discount into account,\nthe sale price of 50 units is {{ price(unit_price, 50) }} EUR.\n```\n\nIf you defined a `price()` function, this could translate into:\n\n```\nThe unit price of product A is 10.00 EUR.\nTaking the standard discount into account,\nthe sale price of 50 units is 450.00 EUR.\n```\n\n\u003e The result of a macro can be **HTML code**:\nthis makes macros especially useful\nto make custom extensions to the syntax of markdown, such as buttons,\ncalls to email, embedding YouTube videos, etc.\n\nIt is possible to use the wide range of facilities provided by\n[Jinja2 templates](http://jinja.pocoo.org/docs/2.10/templates/).\n\n### MKNotebooks\n\nhttps://github.com/greenape/mknotebooks\n\nmknotebooks is a plugin for [MkDocs](https://mkdocs.org), which makes it more convenient to include [Jupyter](https://jupyter.org) notebooks in your project documentation.\n\n```\npip install mknotebooks\n```\n\n#### Usage\n\nSimply include any notebooks you want to use in the docs source directory, and add mknotebooks to the plugin section of your `mkdocs.yml` as follows:\n\n```\nplugins:\n  - mknotebooks\n```\n\nYou can optionally execute the notebooks, by setting `execute: true` in the config, and include a hidden preamble script, to be run before executing any cells using `preamble: \"\u003cpath/to/your/script\u003e\"`. The default cell execution timeout can be overridden by setting `timeout: \u003ctimeout\u003e`, where `\u003ctimeout\u003e` is an integer number of seconds.\nBy default, execution will be aborted if any of the cells throws an error, but you can set `allow_errors: true` to continue execution and include the error message in the cell output.\n\nAny static images, plots, etc. will be extracted from the notebook and placed alongside the output HTML.\n\n#### Styling\n\nMknotebooks applies default styling to improve the appearance of notebook input/output cells and pandas dataframes. If these interfere with any other CSS stylesheets that you're using, you can disable these via the following options.\n```\n- mknotebooks:\n   enable_default_jupyter_cell_styling: false\n   enable_default_pandas_dataframe_styling: false\n```\n\n#### Syntax hightlightting\n\nIn order to enable syntax highlighting for code blocks, `pygments` has to be installed and `codehilite` extension has to be enabled in `mkdocs.yml`.\n\n1. Install pygments:\n\n```\npip install Pygments\n```\n\n2. Enable `codehilite` extension in `mkdocs.yml`:\n\n```\nmarkdown_extensions:\n    - codehilite\n```\n\n\n### Autolinks\n\nhttps://github.com/midnightprioriem/mkdocs-autolinks-plugin\n\n\nAn MkDocs plugin that simplifies relative linking between documents.\n\nThe Autolinks plugins allows you to link to pages and images within your MkDocs site without provided the entire relative path to the file in your document structure.\n\n#### Autolinks Setup \n\nInstall the plugin using pip:\n\n`pip install mkdocs-autolinks-plugin`\n\nActivate the plugin in `mkdocs.yml`:\n```yaml\nplugins:\n  - search\n  - autolinks \n```\n\n\u003e **Note:** If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set, but now you have to enable it explicitly.\n\nMore information about plugins in the [MkDocs documentation][mkdocs-plugins].\n\n\n#### Autolinks Usage\n\nTo use this plugin, simply create a link that only contains the filename of file you wish to link to.\n\nFor example, say you have a document structure like this:\n\n```\ndocs/\n├── guides/\n│   ├── onboarding.md\n│   └── syntax_guide.md\n├── software/\n│   ├── git_flow.md\n│   └── code_reviews.md\n└── images/\n    ├── avatar.png\n    └── example.jpg\n```\n\nNormally, if you want create a link to `git_flow.md` from inside `onboarding.md`, you would need to provide the relative path:\n\n```markdown\n# onboarding.md\n[Git Flow](../software/git_flow.md)\n```\n\nThis link is fragile; if someone decides to rearrange the site structure, all of these relative links break. Not to mention having to figure out the relative path.\n\nWith the Autolinks plugin, you simply need to provide the filename you wish to link to. The plugin will pre-process all of your markdown files and replace the filename with the correct relative path, given that the file exists in your document structure:\n\n```markdown\n# onboarding.md\n[Git Flow](git_flow.md)\n```\n\nThe Autolinks plugin also works with `jpg` and `png` files:\n\n```markdown\n# onboarding.md\n![Avatar](avatar.png)\n```\n\n### mkdocs-redirects\n\nPlugin for [`mkdocs`](https://www.mkdocs.org/) to create page redirects (e.g. for moved/renamed pages).\n\n#### Installing mkdocs-redirects\n\n\u003e **Note:** This package requires MkDocs version 1.0.4 or higher.\n\nInstall with pip:\n\n```bash\npip install mkdocs-redirects\n```\n\n#### Using mkdocs-redirects\n\nTo use this plugin, specify your desired redirects in the plugin's `redirect_maps` setting in your `mkdocs.yml`:\n\n```yaml\nplugins:\n    - redirects:\n        redirect_maps:\n            'old.md': 'new.md'\n            'old/file.md': 'new/file.md'\n            'some_file.md': 'http://external.url.com/foobar'\n```\n\n_Note: don't forget that specifying the `plugins` setting will override the defaults if you didn't already have it set! See [this page](https://www.mkdocs.org/user-guide/configuration/#plugins) for more information._\n\nThe redirects map should take the form of a key/value pair:\n\n- The key of each redirect is the original _markdown doc_ (relative to the `docs_dir` path).\n  - This plugin will handle the filename resolution during the `mkdocs build` process.\n    This should be set to what the original markdown doc's filename was (or what it _would be_ if it existed), not the final HTML file rendered by MkDocs\n- The value is the _redirect target_. This can take the following forms:\n  - Path of the _markdown doc_ you wish to be redirected to (relative to `docs_dir`)\n    - This plugin will handle the filename resolution during the `mkdocs build` process.\n      This should be set to what the markdown doc's filename is, not the final HTML file rendered by MkDocs\n  - External URL (e.g. `http://example.com`)\n\nDuring the `mkdocs build` process, this plugin will create `.html` files in `site_dir` for each of the \"old\" file that redirects to the \"new\" path.\nIt will produce a warning if any problems are encountered or of the redirect target doesn't actually exist (useful if you have `strict: true` set).\n\n#### `use_directory_urls`\n\nIf you have `use_directory_urls: true` set (which is the default), this plugin will modify the redirect targets to the _directory_ URL, not the _actual_ `index.html` filename.\nHowever, it will create the `index.html` file for each target in the correct place so URL resolution works.\n\nFor example, a redirect map of `'old/dir/README.md': 'new/dir/README.md'` will result in an HTML file created at `$site_dir/old/dir/index.html` which redirects to `/new/dir/.\n\nAdditionally, a redirect map of `'old/dir/doc_name.md': 'new/dir/doc_name.md'` will result in `$site_dir/old/dir/doc_name/index.html` redirecting to `/new/dir/doc_name/`\n\nThis mimcs the behavior of how MkDocs builds the site dir without this plugin.\n\n\n### « Blogs for MkDocs » (MkDocs-Blog-Plugin)\n\nThis plugin allows you to host a tiny blog section in your MkDocs site.\nMove away, WordPress... well, not really.\n\n#### How does it work ?\nIt's quite simple. 90% of the work is already done by MkDocs itself.\nEach time you will build your MkDocs site or serve it, this plugin will try to find a specific directory in your documentation folder. \nIf it finds it, every document and every subdirectory nested in it will be listed in reverse on the navbar. Plus, if you will have too many documents to be \nlisted at once, the plugin will try to organize your remaining documents in subfolders.\n\n#### How can I install it ?\nYou can install it through pip with this command:\n```\npip install mkdocs-blog-plugin\n```\n\nThen, open your mkdocs.yml configuration file and add these lines:\n```\nplugins:\n    - blog\n```\nLast but not least, enter you docs folder and create a new subfolder and name it blog. This plugin will try to find blog articles inside this directory.\nThen you are ready to begin.\n\n#### How can I add new articles to my blog section ?\nInside docs/blog create a folder for each year you are planning to add new articles. Then, inside each year folder create twelve folders, numbered from 01 to 12 for each month. \nFinally, in each month folder for each day create a corresponding folder but remember to add a leading zero (for example: 08, 09, 10, ...) \nNow, for every article you will go inside the corresponding `year/month/day folder and you will create a new file there. While it is not necessary that you keep this \nstrict naming convention, this will help the plugin to understand when your article was made.\n\nFor example, this is how I manage my blog folder:\n\n```\ndocs\n├── blog\n│   ├── 2019\n│   └── 2020\n│       ├── 01\n│       │   ├── 20\n│       │   │   └── first-article.md\n│       │   └── 26\n│       │       └── second-article.md\n│       ├── 02\n│       │   ├── 01\n│       │   │   └── third_article.md\n│       │   └── 09\n│       │       └── fourth-article.md\n│       └── 03\n│           └── 16\n│               └── fifth-article.md\n└── index.md\n```\n\n#### Customizing the plugin\n\nYou can customize this plugin by adding some parameters in the mkdocs.yml file, like this:\n\n```\n- plugin:\n      - blog:\n          format: \"(%m/%d/%y)\"\n          text-align: \"right\"\n```\n\nHere is a brief list of every parameters supported by the current version of the plugin:\n\n\n- folder\nThis is the section / folder in which we'll try to build our blog\nDefault value: \"blog\"\n\n- articles\nHow many articles do we have to display on our blog at once? More articles will be displayed in the corresponding subsection\nDefault value: 6 articles\n\n- more-articles\nLet's allow our user to slightly customize the \"previous articles\" section. How do we have to name this section if it will contains more articles? Remember to put a percentage character wherever you want this plugin to insert the number of available articles.\nDefault value: \"More articles (%)\"\n\n- pagination\nWhich name do we have to give to each subsection inside our \"more articles\" section? Remember to put two percentage characters wherever you want this plugin to insert the actual number page and the total amount of pages made.\nDefault value: Page % of %\"\n\n- display-more-articles\nCan we display the previous articles section, or is it better if we hide it?\nDefault: True\n\n- display-article-date\nCan we display the article date in the navbar, or is it better if we hide it?\nDefault: True\n\n- format\nHow we have to display an article publication date on our navbar?\nYou can use these placeholders inside your string:\n\n```\n%d = Day\n%m = Month\n%y = Year (2-digits)\n%Y = Year (4-digits)\n```\n\nDefault value: \"[%d/%m]\"\n- text-align\nDo we have to display an article publication date on the left side (\"left\") or on the right side (\"right\")?\nDefault value: \"left\"\n\n\n### Other plugins to consider\n\nhttps://github.com/spotify/mkdocs-monorepo-plugin\nhttps://github.com/byrnereese/mkdocs-git-committers-plugin\n\n\n### Custom callbacks with mkdocs-simple-hooks\n\nPlugin docs https://github.com/aklajnert/mkdocs-simple-hooks\n\nLet's say you want to copy the `README.md` file to `docs/index.md`. To do that, create a new file, e.g.: `docs/hooks.py`, and put the following function there:\n\n```py\nimport shutil\n\ndef copy_readme(*args, **kwargs):\n    shutil.copy(\"README.md\", \"docs/index.md\")\n```\n\nNow, register the hook in your mkdocs.yml:\n\n```yaml\nplugins:\n  - mkdocs-simple-hooks:\n      hooks:\n        - on_pre_build: \"docs.hooks:copy_readme\"\n```\n\nIdea for list of hooks can be obtained on  https://www.mkdocs.org/user-guide/plugins/#events\nand ideas what you could generally intercept on which level can be obtained from https://github.com/mkdocs/mkdocs/wiki/Event-Based-Plugin-API\n\nevent       | vars   | Possible usage\n----------- | ------ | --------------\npost-config | config | Alter config or prepossessing based on config values\npre-nav     | config, nav-item | Alter/intercept a nav item's creation\npost-nav    | config, nav-item, global nav (so far) | Alter a just created nav item\npre-build   | config, global template vars, global nav | Alter global nav, template vars, etc.\npre-page    | config, template, context | Alter single page and/or template\npost-page   | config, rendered template | Page specific post-processing\npost-build  | config | project wide postprocessing\ndeploy      | config | provide a deploy script (only fired from deploy command)\npre-serve   | config, server_instance | add addition files/dirs to watcher (only fired from serve command)\n\n\n### Working with adr tools\n\nThe first step is to initialize ADRs for our project \n\n```sh\nadr init doc/architecture/decisions\ndocs/architecture/decisions/0001-record-architecture-decisions.md\n```\n\nAfterwards, our project directory structure looks similar to this one:\n\n```\n├── docs\n│   └── architecture\n│       └── decisions\n│           └── 0001-record-architecture-decisions.md\n```\n\nAs we can see, a first decision already has been added to the project: It’s the decision to record our architecture decisions.\n\nWhen opening the ADR file we’re able to read the following Markdown file:\n\n\n```\n# 1. Record architecture decisions\n\nDate: 2020-11-03\n\n## Status\n\nAccepted\n\n## Context\n\nWe need to record the architectural decisions made on this project.\n\n## Decision\n\nWe will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).\n\n## Consequences\n\nSee Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).\n```\n\nCreating new Architecture Decision Records\nWe’re ready now to create our first ADR. The command adr new allows us to create a new ADR with the given title.\n\n```sh\n ./bin/adr new Use sphinx as our knowledge base system\n```\n\nWe’re adding another ADR:\n\n```sh\n./bin/adr new Use PlantUML for diagramming\n./docs/architecture/decisions/0003-use-plantuml-for-diagramming.md\n```\n\nListing Architecture Decision Records\nWe may list existing ADRs using adr list like this:\n\n```sh\n./bin/adr list\n./docs/architecture/decisions/0001-record-architecture-decisions.md\n./docs/architecture/decisions/0002-use-sphinx-as-our-knowledge-base-system.md\n./docs/architecture/decisions/0003-use-plantuml-for-diagramming.md\n```\n\nSuperseding a Decision\nNow we will supersede a decision, for example if a new ADR supersedes our decision #2, we would type in the following command:\n\n```sh\n./bin/adr new -s 2 Use mkdocs as a knowledge base system\n./docs/architecture/decisions/0004-use-mkdocs-as-a-knowledge-base-system.md\n```\nThis produces new ADR file with a reference to the superseded ADR.\n\nOf course our old decision is changed, too including a reference to the new ADR and setting its status to “Superseded”\n\nGenerating Graphs\nTo gain an overview of our ADR’s relations we may generate a graph in the DOT format using adr generate graph like this:\n\n```sh\n./bin/adr generate graph\ndigraph {\n  node [shape=plaintext];\n  subgraph {\n    _1 [label=\"1. Record architecture decisions\"; URL=\"0001-record-architecture-decisions.html\"];\n    _2 [label=\"2. Use sphinx as our knowledge base system\"; URL=\"0002-use-sphinx-as-our-knowledge-base-system.html\"];\n    _1 -\u003e _2 [style=\"dotted\", weight=1];\n    _3 [label=\"3. Use PlantUML for diagramming\"; URL=\"0003-use-plantuml-for-diagramming.html\"];\n    _2 -\u003e _3 [style=\"dotted\", weight=1];\n    _4 [label=\"4. Use mkdocs as a knowledge base system\"; URL=\"0004-use-mkdocs-as-a-knowledge-base-system.html\"];\n    _3 -\u003e _4 [style=\"dotted\", weight=1];\n  }\n  _4 -\u003e _2 [label=\"Supercedes\", weight=0]\n```\n\nWe may write this output to a file e.g. \n\n```sh\n./bin/adr generate graph \u003e ./docs/architecture/graph.dot\n```\n\nFrom this DOT file we may create an image e.g. using GraphViz like this:\n\n```sh\ndot -Tpng ./docs/architecture/graph.dot -o./docs/architecture/graph.png\n```\n\nThis is what the generated graph looks like as png-image:\n\n![alt text](./docs/architecture/graph.png \"Graph\")\n\n\nGenerating Table of Contents\nTo include the ADRs in other documents we may generate a table of contents for our ADRs using adr generate toc like this:\n\n```sh\n./bin/adr generate toc\n```\nThis returns the following Markdown code:\n\n```\n# Architecture Decision Records\n\n* [1. Record architecture decisions](0001-record-architecture-decisions.md)\n* [2. Use sphinx as our knowledge base system](0002-use-sphinx-as-our-knowledge-base-system.md)\n* [3. Use PlantUML for diagramming](0003-use-plantuml-for-diagramming.md)\n* [4. Use mkdocs as a knowledge base system](0004-use-mkdocs-as-a-knowledge-base-system.md)\n```\n\n\nLinking Architecture Decision Records\nWhen ADRs are linked somehow we want to document this and adr link eases this for us.\n\nLet’s use an example where ADR #5 amends ADR #3 so that we could link both with the following command:\n\n```sh\n./bin/adr link 5 Amends 3 \"Amended by\"\n```\n\nNow graph will look like \n\n\n```sh\n\n./bin/adr generate graph\ndigraph {\n  node [shape=plaintext];\n  subgraph {\n    _1 [label=\"1. Record architecture decisions\"; URL=\"0001-record-architecture-decisions.html\"];\n    _2 [label=\"2. Use sphinx as our knowledge base system\"; URL=\"0002-use-sphinx-as-our-knowledge-base-system.html\"];\n    _1 -\u003e _2 [style=\"dotted\", weight=1];\n    _3 [label=\"3. Use PlantUML for diagramming\"; URL=\"0003-use-plantuml-for-diagramming.html\"];\n    _2 -\u003e _3 [style=\"dotted\", weight=1];\n    _4 [label=\"4. Use mkdocs as a knowledge base system\"; URL=\"0004-use-mkdocs-as-a-knowledge-base-system.html\"];\n    _3 -\u003e _4 [style=\"dotted\", weight=1];\n    _5 [label=\"5. Use PlantUML for diagramming with use of stdlib\"; URL=\"0005-use-plantuml-for-diagramming-with-use-of-stdlib.html\"];\n    _4 -\u003e _5 [style=\"dotted\", weight=1];\n  }\n  _4 -\u003e _2 [label=\"Supercedes\", weight=0]\n  _5 -\u003e _3 [label=\"Amends\", weight=0]\n}\n\n```\n\nOr as an image:\n\n![alt text](./docs/architecture/graph2.png \"Graph2\")\n\n\nNote, that in addition both ADR files were updated.\n\n\nMore to read:\n\n- http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions\n- https://github.com/npryce/adr-tools\n- https://www.fabian-keller.de/blog/documenting-architecture-decisions\n- https://adr.github.io/\n- https://github.com/joelparkerhenderson/architecture_decision_record/blob/01cc3c801b1cc61f82391a0a08986e4145e21c56/README.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoronenko%2Frunbooks-mkdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoronenko%2Frunbooks-mkdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoronenko%2Frunbooks-mkdocs/lists"}