- Docker
OR
- python3
- pip
- mkdocs-material (it should install mkdocs automatically)
- mkdocs-markdownextradata-plugin
- mkdocs-git-revision-date-plugin
If you prefer to go with locally installed python
and pip
, then:
pip install -r requirements.txt
mkdocs serve
(binds tohttp://localhost:8000
)
If you prefer going the docker-compose
way:
docker-compose up
(binds tohttp://localhost:8000
)
If you prefer plain docker
:
docker run -it --rm -v ./:/docs -p 8000:8000 strongboxci/mkdocs:base mkdocs serve
Execute one of these (depending on your local setup):
mkdocs build
docker run -it --rm -v ./:/docs -p 8000:8000 strongboxci/mkdocs:base mkdocs build
Run the following and then browse to localhost:8000
:
docker-compose up
- When adding new pages it is preferable to have the filename with lowercase characters.
- The first line of the page should be
# Page Title
- this helps in the indexing and search afterwards. - Avoid using
h1
(i.e# my header
) at places other than the page title. Having multipleh1
confuses theTable of contents
section so please avoid that as well. - If you are adding a
resource
likePDF
,image
,XML
file, it should be placed under./docs/assets/resources/
. - Use
{{resource}}/path/to/asset
when linking to the resource. You can also use{{url}}
and{{assets}}
depending on which link you need. - An exception is when linking to internal docs. Just use relative URLs to the markdown file. Mkdocs will take care to build the links. Follow this guide.
- Please avoid using
inline links
and usereference links
instead as it makes maintenance easier.
Avoid this example:Prefered example:[I'm an inline-style link pointing to Strongbox](https://github.com/strongbox/strongbox) and here is some text in addition so that I can then add again the same link [I'm an inline-style link pointing to Strongbox](https://github.com/strongbox/strongbox)
[I'm a reference link to Strongbox] and here is some text in addition so that I can then add again the same link [I'm a reference link to Strongbox], we can have this link repeating forever in the document and easily change it by just changing it from where reference is. ([I'm a reference link to Strongbox] just for fun.) // insert somewhere at the bottom of the page [I'm a reference link to Strongbox]: https://github.com/strongbox/strongbox
Shortly after you open a pull request, a hook will trigger live preview deployiment to netlify.com. You will be able to check your PR live at the link deploy/netlify
provides in github's PR checks section.
We have divided the documentation into 3 sections:
User guide
- pages with instructions for how to use Strongbox as a normal "user".Developer guide
- pages with instructions for developers who are interested in contributing.Knowledge base
- pages which explain some of our concepts as well as other important information.