4 ms·
Building a Docs Site with Jekyll + GitHub Pages
- alexdevkar 14y agoWhat alternatives to people recommend?
- m3ntat 14y agoNot the same thing (since this isn't an API), but I like what balanced does: https://github.com/balanced/balanced-api https://github.com/balanced/balanced-api
- hoov 14y agoI'm using a Jenkins build to run Sphinx on my Python projects. Having to move the changes into the gh-pages branch is a bit awkward, but it's working pretty well.
- m3ntat 14y agoNice writeup. The whole "your docs site is just on a different branch" has always been weird to me though. I'm not sure what a better way to do it would be but I don't like these two options: switch branches inline or have a separate clone of the repo.
- yesimahuman 14y agoYea, but theoretically you could set up a new remote repo just for the site, and use a specific branch for it. I think the convenience is well worth the change in process you have to deal with.
- michokest 14y agoAfter going through the pain of keeping separate repos, branches or even apps for content pages, my team migrated to simply using a CMS. Wordpress is a bit of a pain, but we found Harmony (http://harmonyapp.com http://harmonyapp.com) to be great at serving pages with programmable themes (think haml, sass, etc) that marketing people can still edit without bothering a developer.
- mimiflynn 14y agoThis is for project docs and such, not for marketing people but for the people working on the project.
- yesimahuman 14y agoYea, unfortunately this isn't the best setup for non-technical users, but I think it can still be decently done through the github editing features they recently added. I probably won't use this for some of our more content-heavy sites, but I've grown to appreciate hosting static content on Github pages.
- eloisant 14y agoWell, the CMS is the classical way to do it. Using Jekyll and Github is a more recent and innovative way to do stuff, much simpler to use for developers and cheaper because it's free hosting that can scale pretty well. Of course if you want marketing people to edit stuff asking them is use Git is going to be painful.
- wereHamster 14y agoInstall the GitHub app, then tell them to follow these steps: 1) Make your changes. 2) Write a word or two about the changes here (commit subject). 3) Press this button (commit) to record the changes. (repeat 1-3 if desired) 4) Press this button (sync) to sync your changes with your colleagues.