Publish Blog on GitHub Pages

It is easy to create beautiful blog and host it for free on GitHub. Just follow the steps below.

Posts can be written in Texts and include tables, images, footnotes, code and math. See example.

1. Setup account on GitHub

  • Create GitHub account at https://github.com/join. Free plan is sufficient. Switch to new UI design if offered — screenshots below are taken with the new UI design.

  • Check email to verify your address with GitHub. Without this step GitHub will not publish your web site.

  • Download GitHub Desktop from https://desktop.github.com, open the app and enter your GitHub login and password.

2. Create blog from template

  • Open https://github.com/texts/texts.github.io and click “Fork” button.

  • Open “Settings” tab and rename repository to be your account name followed by “.github.io”.

  • Default web site should be available at http://<your account name>.github.io in a minute or two.

3. Add new post

  • Open “Code” tab and click button next to “Download ZIP”.

  • This should open GitHub Desktop app. Select folder where to save your repository.

  • Create new document in Texts, type something, and save it into “_posts” folder of the repository. File should be named as a date followed by post title, with words separated by dashes, for example: “2015-11-25-test.md”.

4. Publish your changes

  • Click on the “1 Uncommitted Change” button in GitHub Desktop, type something into “Summary” field and click “Commit to master” button.

  • Click “Sync” button in the top right corner to upload your changes to GitHub.

  • The new post should be available on your web site in a minute or two.

Tips and tricks

  • Feel free to remove existing .md files in _posts directory.

  • Don’t forget to commit changes in GitHub Desktop and sync them to GitHub.

  • Save images into images folder of the repository, then insert into documents in Texts. The path to image should start with ../images/ in order to work correctly both in Texts and on the web site.

  • If the site is not updated after you sync commits to GitHub check email for any error reports.