/openpaas-doc

OpenPaaS Documentation 🤘🏻

Primary LanguageCSSMIT LicenseMIT

OpenPaaS Documentation website

This is the documentation repository for https://docs.open-paas.org.

Layout

To keep things clear and clean, each OP module must follow the same rules:

  1. Sources goes into _docs/modules/MODULE_NAME/
  2. Each module has an index.md file introducing the module i.e. _docs/modules/MODULE_NAME/index.md
  3. The module category is OpenPaaS MODULE_NAME Module
  4. All module images are going into images/modules/MODULE_NAME folder. You can then access it in your markdown file like ![The image caption]({{ site.url }}/images/modules/MODULE_NAME/image.png)

Develop

The Web site is built using jekyll. You can install jekyll, all its dependencies, cry, or simply run in Docker:

docker run --rm --label=jekyll --volume=$(pwd):/srv/jekyll -it -p 4000:4000 jekyll/jekyll jekyll serve

Open the browser on http://localhost:4000. Once some changes on the sources are detected, Jekyll will rebuild the Web site, you will just have to refresh your browser to get the new page.

Tips and Tricks

Adding a ToC to a page

Thanks to kramdown, which is the default markdown converter in latest Jekyll version, one can add a ToC to any page just with the following block

* Here is the ToC, this line is needed to generate... 
{:toc}

Note that the first line is required, it will not be displayed in the page, but ToC will not be generated if not set. For all the ToC options, have a look here.

Testing on github

Even if the running locally should be the same as the website rendered on docs.open-paas.org, you can check that all is OK by deploying the website on your own github pages.

  1. Create a openpaas-doc repository on your github account
  2. Add it as remote git remote add github https://github.com/YOU/openpaas-doc.git
  3. Create a new branch from where you are working on git checkout -b test-gh. Remove the CNAME file and commit this change (rm CNAME; git commit -am 'Remove CNAME')
  4. Push your local branch to your gh-pages branch on github repository git push github test-gh:gh-pages
  5. Go to the generated website https://YOU.github.io/openpaas-doc

Commits

Please send your changes as pull-requests following the OP coding rules.

Push changes on docs.open-paas.org

You have nothing to do... Once your code has been merged into master, the repository is mirrored on GitHub which provides jekyll support out of the box.