> On Sep 8, 2016, at 2:53 AM, Stefano Miccoli <mo...@icloud.com> wrote: > > >> 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
Agreed. I wouldn't touch it. Also, lost the piece on how it looks, but this is 2016 and there is no excuse for not having a cleanly styled and mobile-friendly site. It affects usability. Is owfs from 1985 or today? > 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. I actually think media wiki is a pretty good model, hosting issues notwithstanding. See below. > > My personal list of important requirements. The new site should be > > 1) static and integrated with git (push to publish) I like git very much, but having to learn it to contribute to a community maintained page is a pretty large barrier. I use it from the CL, but I've heard the desktop app is not good. > 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
------------------------------------------------------------------------------
_______________________________________________ Owfs-developers mailing list Owfs-developers@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/owfs-developers
