[Feature request] create a git book
jellespijker opened this issue · 4 comments
Maybe it is an any idea to create a gitbook ( https://www.gitbook.com/ ) from the articles?
I often point towards article in this repo when I answer a question from a external forum. Having these available as pdf or online book could make it more clear for the not-programmers on there.
I tend to just refer to the Markdown pages on Github's website. The Markdown is written such that Github's renderer displays the documentation for the latest Cura version, and such that all of the links still work on Github. Is that not more or less the same?
It is more or less the same and that is also how I have been using it now.
Benefits of GitBook:
Github integration which allows documentation to live in source control and leverages webhooks to auto-update the documentation site
Supports Embedded content
Supports rich content
Supports limited custom theming/branding
Supports searching
Strong community (700 plugins): https://plugins.gitbook.com/
Supports source code updates and online updates with 2-way auto-syncing
Source: microsoft/fast#941
Github has almost the same features:
- Integrates with source control.
- Supports embedded content.
- Supports rich content.
- (No custom theming.)
- Supports searching.
- Has a strong community with many browser plug-ins.
- Allows source updates and online updates using the web editor.
The link to plugins.gitbook.com redirects me to a 404 page not found at the moment. Maybe that's temporary maintenance, but maybe I misunderstood what sort of plug-ins you meant then.
The only things missing here are the custom theming, and, if you meant that, the ability to extend the Markdown renderer with plug-ins. Since Mistune also needs to be able to render the same content, I will not really be able to use those plug-ins unless I re-implement them myself. I don't care a lot for branding or otherwise adjusting the theme for the pages.
On the other hand, to be fair, Gitbook being geared towards Markdown pages will display the search results better (displaying the content rather than the Markdown source) and displays a menu with the available pages on the side of the page. Browser plug-ins can display the file structure on individual pages, but I don't know of any way to improve the look of the search results, and most people won't have those plug-ins installed anyway.
Still, to me, this feature has too marginal gains for the maintenance burden of learning and maintaining such a system. Sorry!
I understand. Thanks for looking into it to.