> On 08 Sep 2016, at 10:20, Jan Kandziora <j...@gmx.de> wrote:
>
> Face it, simple markup alone will not give you any contributors. Hell,
> non-developer documentation contributors don't want to bother with
> markup at all!
>
> What we need is an interface that makes it easy for *anyone* to
> contribute to the documentation. If we don't have that, we could just
> stick to HTML.
Sorry, but I **strongly** disagree: html if you don’t use some form of template
engine is not sustainable.
Suppose you have 200+ pages, and you need to add a single row in the footer:
should you open all the 200 html files by hand and add the html markup? Should
you write a bash+sed+m4 script and programmatically change all the files? Or
should you just change a single line in a template file and have some processor
regenerate the whole site?
The real question here is not about having hundreds of contributors hacking
docs with an WYSIWYG on-line editor. Our problem is to use a technology which
allows us tho **efficiently** build a decent new owfs.org site.
My personal list of important requirements. The new site should be
1) static and integrated with git (push to publish)
2) future proof (ability to integrate new web technologies as they appear)
3) based on templates
4) allow for easy inclusion of html and css
5) be very lightweight as what regards maintenance.
You guessed it, I wrote the above list with jekyll in mind :-))
I use both jekyll and Sphinx: while Sphinx is the way to go for python or C
docs (http://pyownet.readthedocs.io/en/latest/) it is not flexible enough for
owfs.org, which should be a little more than a bunch of docs.
So consider jekyll https://jekyllrb.com as a system based on
* Markdown: a lightweight markup language, which is much more than *simple*
markup.
* Liquid, which is a template engine
* plain old html and css (you are not forced to use markdown or templates… a
jekyll site could also be 100% html+css)
As a bonus with jekyll you get seamless integration into github (but NO vendor
lock-in since it is fully open source), free hosting on pages.guthub.com, rouge
syntax highlighting…
Stefano
------------------------------------------------------------------------------
_______________________________________________
Owfs-developers mailing list
Owfs-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/owfs-developers
