search

tdwg / dwc

Darwin Core standard for sharing of information about biological diversity.
https://dwc.tdwg.org
Creative Commons Attribution 4.0 International
206 stars 70 forks source link

Use markdown and site generator #73

Closed peterdesmet closed 7 years ago

peterdesmet commented 9 years ago

Except for terms/index.html, terms/decisions.html, and terms/history.html, which are rather complex pages, the other pages would be easier to maintain and update if they were in Markdown (as opposed to html). We already opted for this format for the examples (because we want community involvement) and as a result (currently) decided to link to these pages directly on GitHub instead of having them on the website.

Advantages:

Here's a good list of tools: https://github.com/PharkMillups/beautiful-docs#generating-docs Shortlist:

Tool Last release Stars Remarks
DocumentUp 2012 700 JS from README only
FlatDoc 2014 1337 JS from README only
Dexy 2011 188 Also looks in code.
GitBook 2014 7251 Mainly for books, not sure if hosting on gh-pages is possible
MarkDoc abandoned 233 Through Python script
docgenerator 2012 1 Seems to support multiple Markdown files
Beautiful Docs 2013 200 Via node.js
Jekyll 2014 17133 Blog generator in Ruby
Pelican 2014 3913 Blog generator in Python
Read the docs 2011 1574 Looks great, supports multiple files.
Assemble 2014 2175 Another suggestion by Tim. Has cool documentation.
peterdesmet commented 9 years ago

Discussion about this is happening at issue #76

hlapp commented 9 years ago

:+1: for Read The Docs. Lots of open-source projects use it.

Speaking more generally, I suggest that the overriding consideration not be the ease of implementing some custom way of doing it, but how many people out there are going to be familiar with the technology, sufficiently so to contribute and take over maintenance. For something that's custom-made, that number will always be tiny. Let the Typo3-based tdwg.org website fiasco be a lesson. The less custom stuff is developed for this, the less the risk that it decays due to lack of maintainers.

mdoering commented 9 years ago

The script we have is really simple and anyone knowing python should be able to work with it immediately. I doubt there are more Read The Docs savy people around than python users. But if you know how to do it give it a try with DwC Hilmar and let us know how we can make use of it for this site

peterdesmet commented 7 years ago

Still decided to move guides from html to markdown, but we won't render them as part of the Darwin Core website. Rather, will link to the guides on GitHub. Closing this issue.