Mobirise github pages generator#

(But it probably should be Read the Docs. The other place could be Read the Docs, an AWS server, a content delivery network, or pretty much anything. Keep your source files in git/Github, and setup a tool(chain) that builds, deploys, and hosts your documentation from Github to some other place.

Don't attempt to keep built output files in version control. The right solution is don't use Github pages. Combined with a large team, the potential for conflicts grows. However, the more complicated the documentation is, the longer the pull-build-push process takes.

With a little scripting, a little luck, and lot of commit privileges, this will work. The worst solution, which might work for a very small team, is to use the gh-pages branch and workflow that attempts to ensure all builds to gh-pages happen in a very fast pull-build-push cycle. Output shouldn't be version controlled, only source files should be version controlled. This means that even though Addison and Bahati each only added a single file, and their work didn't conflict (even a little bit), there is no way to merge back together their built output.Īnd here's the problem with Github pages for complex documentation (that is, anything that needs to be built outside GH). This is the case on 'regular' sites and blogs, but is even more true with technical documentation, where there might be an entire sitemap on the side bar of every page. Tables of contents, menus, internal links. The problem is that a built HTML site - whether it's Jekyll or Sphinx or anything else - has cross references on every page to nearly every other page. Since Bahati understands git about as well as the average developer, this is a problem. Bahati starts by pulling down from upstream (like ya do) and gets a merge conflict. No problem.Ī few minutes later, Bahati - whose work doesn't conflict, even a little bit - finishes up and is ready to do the same. Addison also has commit privileges, and goes ahead and accepts the PR right away. Addison pulls down from upstream (like ya do), runs the build, commits, pushes, and PRs. Now, the end of the day, they are both ready to do a PR. In the course of their work, they have each built locally a handful of times and made one or two commits. They both fork, clone down, and get to work. For the sake of simplicity, let's pretend nothing they do would conflict, even a little bit. This repo is set up to serve Github pages from a /docs/ directory that they are supposed to build to. Suppose Addison and Bahati are two writers each working on their own piece of content in a Sphinx repo.

Mobirise github pages generator#

But if you need to run a build yourself - because you're using another generator like Sphinx, Nikola, or Mkdocs - or because you have some Jekyll plugins that aren't supported in Github - you'll have problems once you add a second writer. Better, perhaps, because adding or modifying content doesn't cause conflicts and run-time errors. The Open Source collaboration model applies as well to content as it does to code.

If you let Github build your site automatically from Jekyll or plain markdown files, everything works great. If it's a built HTML site, Github just serves those files. If it's plain markdown or Jekyll, Github builds and deploys for you. The source can either be an unbuilt Jekyll site source, plain markdown files, or a fully built static HTML (+CSS +JS) site. You designate a particular branch or directory of a branch as the Github pages source. (Or even, as I discovered, a single writer on more than one machine.) But, I've recently realized there's a problem with it that makes it ill-suited for multiple collaborators working on complicated documentation. I used it to host documentation for my most recent tech writing gig.įor a single writer with moderate or better technical skills looking for a simple hosting solution, it's amazing. I run this blog, my personal blog, and my music and liturgy blog on it.