info.michael-simons.eu

I wanted to start publishing to GitHub Pages from my learning and experimenting project simple-meetup. One of the learning scopes of the above project is “code as documentation” and the question to which extend such a project can be used to write articles and generate documentation. In this project I’m using Asciidoctor and the Gradle Plugin as suggested by my friends Ralf and Gernot in their column Hitchhiker’s Guide to Docs as Code and corresponding repo.

GitHub Pages can be setup separately for every repository and you can choose to select a branch for your HTML-files. As I didn’t plan this upfront, I obviously didn’t have an empty branch for that and I didn’t want to create one and have all the other commits in it. Enter --orphan for the checkout-command:

--orphan
Create a new orphan branch, named , started from and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new history totally disconnected from all the other branches and commits.

The index and the working tree are adjusted as if you had previously run “git checkout “. This allows you to start a new history that records a set of paths similar to by easily running “git commit -a” to make the root commit.

See checkout --orphan.

Run git checkout --orphan gh-pages and you’ll end up with a new branch called gh-pages with all the files you have staged, but they can be safely removed with git rm -rf . and then the branch can be committed and pushed.

If you’re wondering what I am doing with that branch: Part of the build are ideas from the docToolchain. I am generating articles with this stance in Gradle:

tasks.withType(AsciidoctorTask) { docTask ->
    dependsOn check
 
    attributes \
          'sourceDir': "$projectDir/src/"
 
    sourceDir = new File("src/articles")
    outputDir = new File(project.buildDir, "articles")
    resources {
        from(sourceDir) {
            include '*.png'
        }
    }
}
 
task generateHTML (
        type: AsciidoctorTask,
        description: 'use html5 as asciidoc backend'
) {
    backends = ['html5']
}
 
defaultTasks "clean", "build", "generateHTML", "generatePDF"

This generation is an essential part of the build and it runs by default. In my Travis CI script I have the following after_success hook:

after_success:
- cd build/articles/html5
- git init
- git config user.name "${GH_USER_NAME}"
- git config user.email "{GH_USER_EMAIL}"
- git add . ; git commit -m "Deploy to GitHub Pages"
- git push --force --quiet "https://${GH_TOKEN}@${GH_REF}" master:gh-pages

It changes to the output directory, reinitializes the repository there and force pushes the new master to the remote gh-pages branch. The variables are my GitHub username and a token I created for the purpose of having Travis to be able to push.