8/19/2023 0 Comments Gitbook editor manjaro![]() ![]() I'm going to try to summarize this discussion. Someone please correct me if I've gone off the rails. The beauty of this approach is that it separates the documentation source from the presentation. In our GitHub repo, we set GitHub Pages to publish to the web using main/docs, which means that visitors can browse the source files at the root level, and view the HTML web pages hosted in the docs subfolder. In mediawiki, it's all wrapped up together and lives in the mediawiki database. We use the GitHub Pages custom domain setting so that the HTML edition is available at. Migrating away from mediawiki is tough because the content must be converted. In the new model, the documentation is just markdown - Very standard and portable. It's easy to control in a git repo and easy to move to another location if github goes goofy. Presentation is taken care of by converting the markdown to something else. This isn't exactly 'compiling' but let's call it that for now. Gitbook is one tool for generating html from markdown but there are others as well (readthedocs comes to mind) The resulting html can be hosted anywhere. ![]() If we move to a model like this, we're no longer tied to any service or software. We could change git hosts, hosting locations, compiling mechanisms etc quite easily. ![]() The gitbook software (legacy) is open source. If you want, you can run it locally to 'compile' the html version of the documentation. The legacy gitbook service does this automatically and also hosts the output html. There's a community around the gitbook open souce software that has developed plugins and extensions to generate. During the compile phase, it can include links so users can download for offline reading. The weakest part of the toolchain is the online web-based editing which is the one place a wiki shines. Editor GitBook's documentation editor supports rich text, various content blocks, and Markdown. There's no doubt that this will continue to improve in the future but it's pretty weak right now. Rich text Learn how to add relative and absolute links and other rich text. Blocks Learn about editing blocks and add your REST API specs automatically. Inline content Learn how to add inline images, links and other content. If our documentation was getting a lot of edits from random drive-bys, I would be concerned. But most come from the core contributors. There are tools to make editing and maintenance friendly. If one doesn't like editing markdown, there's a desktop editor which may have some git support built in. I haven't tried it.īy comparison, the new gitbook (which I DON'T think we should use) works much the same way but the code to go from the markdown to html is proprietary. They put a lot of focus on the web-based editing but eliminated most of the plugin support in the process. They are very much trying to build a business here. The new service still hosts the html on their site but also provides the nifty web-based editor. New changes made through the editor become commits in the source repo as markdown. I played with this on my own and I don't think it's ready for primetime. Using it would also tie us to gitbook more than we want. They seem to be friendly to FOSS projects for now but who knows.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |