Switch to mkdocs - Githubissues

intellij-dlanguage / intellij-dlanguage.github.io

0 stars 1 forks source link

Switch to mkdocs #2

Open andre2007 opened 6 years ago

andre2007 commented 6 years ago

I did some closer look on mkdocs as tool for generating a nice documentation site for intellij-dlanguage.

An example page created with mkdocs you can see here: http://opensciencegrid.org/security/

The concept is rather easy. On master branch you write the markdown files. There is a second branch gh_pages which contains the generated documentation based on the markdown files. A travis CI job automatically creates and upload the files to the gh_pages branch on push to master branch.

Setting up travis ci is described here https://djw8605.github.io/2017/02/08/deploying-docs-on-github-with-travisci/

SingingBush commented 6 years ago

I'm open to using mkdocs. As this is a organization page though there's no gh_pages branch, we just push to master.

andre2007 commented 6 years ago

I am not sure what you mean with organization page. I think 2 branches are necessary:

master: contains the source code (the markdown files). Merging pull requests into master triggers the Travis CI job to compile(translate) the markdown files into html files
gh_pages: contains the generated html files. https://intellij-dlanguage.github.io/ will point to the gh_pages branch

Maybe it is possible to have the markdown and the generated html files in 1 branch (master) but then you have to invest more time into the travis CI logic. Pushing the generated html files should not trigger the mkdocs process again -> endless loop

andre2007 commented 6 years ago

I started to create a mkdocs prototype. Unfortunately the actual version of mkdocs has a bug while deploying to User/Organization pages. https://github.com/mkdocs/mkdocs/issues/1525 This bug will be solved with next version of mkdocs. I assume version 0.17.6. When the version is available I will continue working on this topic.

waylan commented 6 years ago

This bug will be solved with next version of mkdocs. I assume version 0.17.6.

Not version 0.17.6, but version 1.0. This was not a bug with a simple bugfix. Previously, MkDocs did not support User/Organization pages. To add support, we needed to make a backward incompatible change to how relative paths in the config file are resolved (see mkdocs/mkdocs#1376 for details). Therefore, this change will be part of a major release.