I appreciate Medium as an aggregator. I love that it shows me many different articles, that I can filter for interest, and that I can clap to support my friends. However, it leaves a few things to be desired. It stores my posts in one place, but my profile page does not say much about me. I would also like to have a backup of my blog posts for my own use (in case anything happens to Medium). It would be nice to have my blogs connected to a personal site that also my projects, LinkedIn, and resume.
Enter Github Pages. This allows me to quickly set up a personal blog site I can link to. It also allows me to write in Markdown, which I find much simpler than Medium's formatter, and I can save my blogs with git. I can then use Markdown to Medium to export my blog to Medium.
GH pages will host what is called a 'static site.' This means that your website is only html, css, and js (no server). You could write the html and css yourself. Alternatively, (as Github recommends), you can use a tool called Jekyll to generate a static site for you. You only have to write your blog posts, and you can let Jekyll worry about formatting.
For initial Github Pages setup, you can follow the basic introduction. Make sure your repository name is [your-username].github.io. The url for your page will end up being the same. If you have followed the directions, you will have a bare-bones site with "Hello World" in an index.html. Rather than dealing with HTML, let's set up Jekyll.
Jekyll uses markdown instead of html. If you are unfamiliar with markdown, it is just a way to spice up plain text. It is much like writing a simple text file, but you use some formatting to add headers, images, tables, and more. I find it very intuitive, but your mileage may vary. If you want to see the markdown for my blogs, the repository is here. Most of my pages are very simple, except the occasional image file.
Here is where it gets just a bit hairy. The link to Jekyll with Github Pages is here, but the documentation is not ideal. Rather than repeat the steps that are in the help center, I will give a high-level overview, then mention where I struggled.
The first few steps involve setting up a git repository, and what branch/directory you should be in. If you are reading my humble blog, you are probably making a personal site. I would just recommend being on the master branch, and I would not bother to designate a publishing source directory.
The docs then go on to use bundle exec jekyll VERSION new ., which didn't quite work for me. I adapted this Stackoverflow post. I did not use Jekyll 4.0.0, as that was not in the recommended versions for github. Instead, I made sure that the version in the Gemfile matched the recommended, and simply called bundle exec jekyll .. It offered to rewrite everything in the directory (which was fine by me). It then generated the Jekyll site, and retained my git repository.
You can run your site locally with bundle exec jekyll serve. This will create some html documents and put them in _site/. In addition, whenever you change a post, the site will update itself. You will still have to reload the page in your web browser.
This is pretty straightforward, as long as your site is working at this point. Make sure to commit and push to test it on Github. Jekyll will create a basic post for you, so you can see what they should look like. Posts are just markdown, with some metadata at the top. Each post filename needs to have the format YYYY-MM-DD-title.md, and should live in the _posts directory. In addition to posts, there are "pages," which are more general. These would be related to the site as a whole. Jekyll gives you an example page, an "About" page, which is linked to everywhere in the site. Pages go in the root directory.
The initial setup has the site title "Your Awesome Title," as well as social media links to Jekyll. To change these global values, look at _config.yml. Note that the formatting for the config's social links is different depending on the theme and version. At the time of writing this, I was using the minima theme, with Github default 3.8. This used the format github_username. However, the theme's repository was up to version 4.0, and the format was minima.social.github.
I used Jekyll because it is easy to set up, and gives you some out-of-the-box styling. You can mess with this further, but it can get very complex very quickly. I won't attempt to go over the details, just some initial problems you could run into. You can change the theme of the site in the _config. Github Pages comes with some built-in themes, and the default is minima. You can change to another theme by looking at the directions on their own repository, but there are caveats.
The problem with other themes is their layouts. Layouts go in the _layouts directory, and set up the look of your site. The minima theme includes default, home, page, and post layouts, so you already have the formatting for a blog. Remember that you need metadata at the top of your markdown files, and that includes the layout. Since minima already has these themes, you don't need to deal with them. However, for the other built-in themes, they usually only have a default theme. You can try creating your own _layouts directory and copying the ones from minima, but that does not always look great. If you want to work with another theme, you will have to do quite a bit of modification and planning.
Sometimes you will want images in your blogs. Fortunately, Jekyll makes this easy to deal with. If you add an assets/ folder to your base directory, it will be automagically included in the final site. For example, I used assets/images/, and I could then link to my image with standard markdown: .
I like writing my blogs in plain text. Writing them in markdown allows me to export them to Medium, and still retain them on hand. Jekyll requires a bit of initial setup, but then is pretty smooth sailing for a quality outcome.