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