Open bdarcus opened 4 years ago
Here's another model, using pandoc.
https://github.com/commonmark/commonmark-spec/
It is published by github (and has multiple versions), but I'm just unsure how.
❯ curl -Is https://spec.commonmark.org/
HTTP/2 200
server: GitHub.com
Ah; published on a separate repo, which has a single gh-pages branch.
https://github.com/commonmark/commonmark-spec-web
Each version has a separate directory, and each of those has both a copy of the markdown spec.txt
file AND the rendered HTML.
So they use gh-pages for serving the content, but pandoc to generate it.
In theory, something like that could work for CSL, the source spec doc(s) move to the main repo, and the documentation repo becomes a publishing platform.
If you go literate, we will have to use pandoc somewhere along the way. But of course not for publishing.
Last question (for the moment) is publishing platforms and workflow.
Current docs are published on readthedocs.
There are good reasons for this, and lots of projects use this platform.
But using github pages might give us more flexibility.
A related question (also to #2) is processor. Github Pages has a CommonMark processor available, so if we kept split (see #1) we would avoid having to use pandoc.