Skip to content

strongbox/strongbox-docs

Repository files navigation

Pre-requisites

  • Docker

OR

  • python3
  • pip
  • mkdocs-material (it should install mkdocs automatically)
  • mkdocs-markdownextradata-plugin
  • mkdocs-git-revision-date-plugin

Getting Started

If you prefer to go with locally installed python and pip, then:

  1. pip install -r requirements.txt
  2. mkdocs serve (binds to http://localhost:8000)

If you prefer going the docker-compose way:

  1. docker-compose up (binds to http://localhost:8000)

If you prefer plain docker:

docker run -it --rm -v ./:/docs -p 8000:8000 strongboxci/mkdocs:base mkdocs serve

Building

Execute one of these (depending on your local setup):

  1. mkdocs build
  2. docker run -it --rm -v ./:/docs -p 8000:8000 strongboxci/mkdocs:base mkdocs build

Live Pre-view:

Run the following and then browse to localhost:8000:

docker-compose up

Guidelines For Contributors

  • 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 multiple h1 confuses the Table of contents section so please avoid that as well.
  • If you are adding a resource like PDF, 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 use reference links instead as it makes maintenance easier.
    Avoid this 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)
    
    Prefered example:
    [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
    

Pull Requests

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.

Structure

We have divided the documentation into 3 sections:

  1. User guide - pages with instructions for how to use Strongbox as a normal "user".
  2. Developer guide - pages with instructions for developers who are interested in contributing.
  3. Knowledge base - pages which explain some of our concepts as well as other important information.