Skip to content

Concepts ↵

Working with diataxis documentation

To update the documentation on any of the sections just add a new markdown file to the designated subfolder below 

├───concepts
├───tutorials
├───how-to
│   └───troubleshooting
└───reference
    ├───architecture
    ├───decisions
    └───faq

Note: each folder contains templates that can be used as quickstarts

See Diataxis documentation for more information on diátaxis.

Ended: Concepts

Tutorials ↵

Getting Started

Prerequisites

To effectively debug or deploy the application, read or provide the following:

Steps

Reference

Starting the documentation server

When updating documentation its a good idea to start the documentation server

Prerequisites

  • Running docker desktop
  • Powershell
  • Cloned repository

Steps

  • Navigate to root of the solution, containing both mkdocs.yml and RunDocsServer.ps1
  • Execute ./RunDocsServer.ps1 to start the documentation server. When successfull you should see Serving on http://0.0.0.0:8000/
  • Navigate to: http://localhost:8000

After the document server is started you can leave it running while you edit/add/remove the files of your documentation and the site will update automatically. In some instances you may have to ctrl+f5 refresh cache, when the menu is updated for instance.

Ended: Tutorials

How to ↵

Load repository file into documentation

Sometimes you need to render a file which is part of the repository.

Prerequisites

The file needs to be available to the docker image running, so you will need to provide it.

Local doc server

  • add it to a binding, either through directory or individual files. *recommended is to bind the file to a location in the resources directory( )

Render the file

**[Features](#features) • [Get Started](#get-started)**

This project can be used as a template for repository documentation.
It's goal is two-fold:

- provide usage examples on how a diataxis based documentation could work including features from mkdocs that allow lighting up the content.
- provide a drop-in documentation framework anyone can just intall into their repository

To see a working example, see [diataxis-template](https://diataxis-template.readthedocs.io/en/latest/).
Pro-tip: make sure you add the link to the working example so you can off-load learning how to use the template to the example

### Features

- [x] Basic diataxis structure
- [x] MkDocs basic config
- [x] Convention based folder structure using awesome-pages
- [x] read the docs
- [X] Basic templates
- [X] Printing of the entire site
- [ ] Distribution scripts

## Get Started

- See [Getting Started](tutorials/getting-started) for a tutorial on getting started with development
- See [Tutorials](tutorials/) section for all tutorials

## FAQ

See [faq](reference/faq.md) for a list of known issues.

## Contributing

Please see [contributing guide](reference/contributing.md) for more information.

## License

See [license page](reference/license.md) or `LICENSE.md` file for more information.

## Acknowledgements

Diataxis templates was based on [adolfomaltez/diataxis](https://github.com/adolfomaltez/diataxis)

References:

- [Awesome pages plugin](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin)
- [Page tree plugin](https://github.com/tombreit/mkdocs-pagetree-plugin)

see docs for more information on how to use this snippet

Start the documentation server

To edit and view locally, run:

RunDocsServer.ps1

Then visit localhost:8000

References

Ended: Troubleshooting

Ended: How to

Reference ↵

Ended: Decisions

Ended: Faq

Contributing

Contributing is much appreciated.

How to contribute

Please create a PR

Bug report

Please create a issue

Diataxis documentation

This project uses the Diátaxis technical documentation framework. There are 4 main parts:

Working with diataxis documentation

see working with diataxis documentation

Ended: Reference