Proposed Format Changes (Jekyll, Markdown, etc)

[hacking-and-coffee]

Proposed Format Changes (Jekyll, Markdown, etc)

[indrora]

Points for GH Pages using Jekyll/Markdown:

• Produces a perfect archive: WYSIWYG in terms of content, from what I understand.
• Clone a repo = get the content
• GitHub does the work for you -- Mostly.

Points for RTD:

• Uses Markdown or ReStructuredText, with RST being default.
• Uses the well-established Sphinx engine
• Produces [ HTML, PDF, EPUB ] versions as artifacts from each build
• click to edit in GitHub
• RTD does the work for you. Mostly.

Downsides to Jekyll:

• Two independent branches. One is a direct artifact of the other, but it looks funny.
• Only one artifact produced
• Only supports Markdown (from my understanding)
• great for a blog, not so great for a book.

Downsides to RtD:

• Cloning repo = get only sources, not final content
• works best with ReStructuredText
• Some people are anti-scalie haters not a fan of python.
• Uses someone else's infrastructure.

[hon1nbo]

Cloning repo = get only sources, not final content

I think that enough is problematic. So reading through RTD's background for using ReStructuredText as the default is that Markdown doesn't have as much extensible. We don't need that much here, as this isn't intended to be hundreds of pages long (that would default the point of being n00b friendly)
However, at the same time the Markdown used by Github is technically a "flavour" of MD since there is no official standard. However, our MD usage would be fairly basic as we do not have code in this repo. Hence, no having to handle code snippets along the lines of:

import math

versus

~~~python
import math
~~~

as a flavour variant
This still leaves some details such as whether or not we have these differences in markdown interpretation

# Heading 1
#Heading 1

However, I think the majority of users will either A) be using Github, B) the information will still be human readable even without a Markdown viewer, or C) the very few markdown descriptors we actually will end up using will be easy enough to automate converting.

Any thoughts on those points? I doubt most people would run their own jekyll, but they will like the option. My super-secret employer for example would maybe want to run their own, with guidelines for employees that are internal only.
Or maybe it would just be a good idea to not place our eggs in one basket (I certainly don''t with Github).

Cheers,
~H

[sodejm]

I would prefer a move towards Markdown/Github Pages for the sake of simplicity with markdown. It is fairly straight forward to convert and yet still would provide the required format if someone wanted to clone and run pandoc or similar for document conversion to a preferred format. Even though GH technically uses a "flavor" of markdown, the required syntax for this repos use case should be pretty basic and be supported by the majority of markdown readers when cloning or if this ever needs to move towards a different platform for hosting. Also, I do agree that the majority of users are likely to be Github user and we may benefit from a little search engine preference that way (not a validated statement).

[hon1nbo]

I think Markdown is the best move as well. I've talked with several others on different channels (though getting them to move that discussion here has been... trying). I'll set a milestone to move to a GH page eventually, but for now everything is in a Markdown format for the mast part.

[hon1nbo]

This thread can be used for suggestions regarding the style guide as well. It will be closed when the first step in the project is complete.

[hon1nbo]

Markdown it was.