Use Jekyll

[doktorbro]

The master branch is run through Jekyll when you push content to your repository. With this in mind you could simplify the maintenance of documentation. I’ve created an example:

• Repo. Note changes in
  • _layouts
  • _config.yml
  • example.md
  • README.md
• Live.

[sideshowbarker]

Thanks for raising this. I'm open to making any changes but so far it's not clear to me how the specific changes in your example are an improvement.

The master branch is run through Jekyll when you push content to your repository.

OK. But I don't understand how that's relevant if I've already got the gh-pages branch set as the default and am publishing to http://validator.github.io from that.

Are you're saying that I should switch to just using the master branch? And I could publish to http://validator.github.io from there somehow? Or would I still need both branches?

And If you're proposing I switch to relying on Jekyll, I'm open to that. But at this point I don't yet understand what that would buy me. If I did that, could I continue to maintain my source in HTML, as I'm doing now?

I guess I should point out that I don't know much at all about Jekyll. I've heard about it of course, but I'm really not familiar with it and have never used.

With this in mind you could simplify the maintenance of documentation.

If the proposal is to rely on Jekyll, I agree it would simplify maintenance for somebody who's already familiar with Jekyll and already using it.

But right now I'm just editing the source in HTML and automatically generating markdown from that (locally before I push). Which is a fairly simple setup already.

So anyway, while I've not found they way I'm doing things now to be much of a maintenance headache, but I'd be willing to try something new

[doktorbro]

@sideshowbarker Sorry for not linking to the description, how Jekyll works on Github.

Jekyll does already run on this repositorys master branch, every time you push. You don’t have to create another branch.

You don’t have to use markdown, if you don’t like it. Jekyll copies HTML files as is, that’s why you didn’t notice nothing yet.

The goal for you would be the usage of layouts. It’s an easy to use I’ve updated my example:

• Layout: https://github.com/penibelst/validator.github.io/blob/gh-pages/_layouts/default.html
• Index with layout between triple-dashes: https://github.com/penibelst/validator.github.io/blob/gh-pages/index.html
• Live: http://penibelst.github.io/validator.github.io/index

You could just write the content in HTML like before, while the recurring header and footer parts would live in layouts.

So it’s a really small change, if you don’t want to switch to markdown. Three steps:

• create one extra file (_layouts/default.html)
• outsource the header to it
• reference the layout in pages

Done.

---

Out of curiosity: why do you duplicate the content of index.html in the README.md?

[sideshowbarker]

Out of curiosity: why do you duplicate the content of index.html in the README.md?

I automatically generate the README.md file from the index.html file, using html2text; see:

https://github.com/validator/validator.github.io/blob/master/Makefile

I do it that way in order to have HTML content to display at http://validator.github.io that's styled and formatted the way I want it to be, while also having have a plain-text README.md for https://github.com/validator/validator.github.io display and while also having a plain-text README.md in the release distros.

[doktorbro]

Thank you for the explanation.