In your repository settings you’ll find various options of where to publish your site from.
Whichever of those options you choose, you can drop an index.html in the root of whatever location you chose in the above settings, and that site will be published.
If you have other posts or pages, you can assign one of them the root permalink, in its frontmatter, and in this case you do not need index.html
The first repository for your web-page must be named like so:
username.github.io. For example, the repository for my personal page is called
infominer33.github.io. Simply create a new repository, and if your github username is
@awesomesauce then you would create a new directory named
Every other repository you own can also be made into its own web-page, that will published off of your user page, with the same name following your domain. So if you have a repository called,
/Dynamite and you go into settings select pages to publish from the master branch, then that page will be found at
So github.com/didecentral/didecentral.github.io is published at decentralized-id.com, because I have a custom domain. But it can still be found at, infominer33.github.io/DIDecentralized.
You can install ‘classic themes’ simply by copying (or forking) their repository to a space you control, and change them by editing their files manually. These are just files and folders, with everything where you can see it.
What separates ‘classic themes’ from jekyll themes is a configuration file called
_config.yml. This lets jekyll know how to build your site, and it lets github know it can be built.
The simplest way to use jekyll\github-pages is to choose one of the official GitHub pages themes.
Those basic github themes are mostly for developers who want a page to put up for a software project, or anyone who just wants a basic blog to get started learning. Using the theme chooser, you can get started writing blogs immediately, and begin learning the basics of how jekyll sites are configured.
Once installed, I cloned those repos locally so its easier to see how everything works. Then, if I want to configure a file that’s not in my repository, I have a copy nearby. You can grab the
_layouts/default.html, put it in your repo, and get a feel for how configuring that template shapes your entire site. But then you configure individual pages, and parts of your site to display differently.
GitHub Pages has the following themes built in, you can begin learning with a few clicks:
After you’ve learned the ropes, it’s easy to bring any content you created to a new theme.
Although pages will build an index.html from your readme.md, pages will not behave as expected if you try to do any configuration or additional optimization with only readme.md.
In that index.md you need to include front matter:
--- layout: default ---
There is a plugin that will builds index files from all the readme.md files of your repository.. but it has trouble creating an index.html from your repositories primary README.md.
There are tons of themes available for Jekyll… it’s just not neccessarily easy to figure out how to use them, when you’re first learning. Especially because they’ve all been built with\for different versions of Jekyll.
After I find a theme I like, I fork it and then go to settings and choose master, docs, or gh-pages, depending on how the site is designed, to make sure it’s working. I’ve spent a lot of time configuring themes I didn’t verify I could get running first. Don’t do that :)
When I was first looking for a jekyll theme, I couldn’t get away from this theme in google search results, and had a lot of trouble getting others to work. Minimal Mistakes is probably the most robust and reliable jekyll theme available.
Not only that, it has excellent documentation! You can find pretty much everything you need to run Minimal Mistakes in the Quickstart Guide, Sample Posts and Collections, along with their corresponding files on Github.
Minimal Mistakes is forkable to create a working site, and its a gem-based theme.
I have my own demo site with lots of detailed instructions on how I set them up, you can check out here: web-work.tools/minimal-mistakes/
Here are some themes that have caught my eye, and I know they work.
Code that’ll help you kickstart a personal website that showcases your work as a software developer.
Layouts are preconfigured page templates. When I started, it was too much to think about layouts, and I would use “single” and “page”. Now that I am using blog posts.. (because they populate your RSS feed, and increases their portability) I’m also using the Home layout:
redirect_from: internal/url to change the location you are publishing, but keep old links. Use
redirect_to: https://external.url to send visitors somewhere else (perhaps you want it to live on another site, but not lose your valuable links :)
The strict minimum for the master picture is 70x70. Your picture is 225x225, which is ok. However, it is recommended to use a picture of at least 260x260. If you still want to use your picture, some of the derivated favicons will not be generated, such as the high resolution tile for Windows 8 / IE 11.
Gem files are ruby packages that contain all of the files necessary for building your site, allowing you to keep your repository un-cluttered, and keeps your site up to date, when the gems developer makes updates.
If you want to change a file that’s in the gem, you just create the directory and put the file where it goes, to configure as you wish.
Until GitHub Actions were introduced, you needed to Install jekyll and build them locally, to the
docs directory, which you may have noticed as an option in your repository settings.
For user or organization pages, you can only publish from the master directory. So, this will only work for projects other than your homepage, or your organizations homepage.
Although that’s consistant with everything I’ve read, in practice I’ve found that after forking minimal mistakes, and setting up the gemfile, it will build the site for me. I think the idea is that once the site is completely built, with a
gemfile and a
gemfile.lock, then GitHub Pages uses jekyll to build any updates when you change it’s content\html\css\includes\layouts.
decentralized-id/decentralized-id.github.io’s: ‘_config.yml’) and
gemfile for reference)
There’s also using the gh-pages branch, but that’s getting a little more technical.
Until you’ve set up a few different sites, and figure out the ins and outs, each new site takes some tinkering to get working.
You will find that GitHub error messages are not very descriptive. Buidling your site locally is the best way to figure out why GitHub Pages can’t build your site.
You can set the destination in your
_config.yml, otherwise jekyll will build to the
_site directory, which is usually added to your
If you’re publishing from the
docs directory, be sure and don’t add that to your
.gitignore, since you want your website uploaded to GitHub to be published..
Then add the gem and its source, also add any plugins you are using:
source 'https://rubygems.org' gem "minimal-mistakes-jekyll" gem "jekyll-paginate" gem "jekyll-sitemap" gem "jekyll-gist" gem "jekyll-feed" gem "jemoji" gem "jekyll-include-cache"
Hopefully you have installed
git, by now. You’ll need that to push any local changes to GitHub.
Then use bundler to install the theme
Build gives an error message if the build fails
bundle exec jekyll build
Serve builds and “serves” a local browsable copy
bundle exec jekyll serve
Trace gives details on errors (but won’t always show your problem)
bundle exec jekyll build --trace
Verbose… you get the idea.
bundle exec jekyll build --verbose
This makes it simpler to keep your source files up to date. However, it is much slower than using gems to build locally (which only really matters if your site has a lot of content).
plugins: - jekyll-remote-theme remote_theme: benbalter/retlab
Essentially, if you’re just editing files on github, you should just add those lines to your _config.yml along w an index file and Jekyll should build your site.
Wax is inspired by FAIR data principles, and as such strives to make its collections findable, accessible, interoperable and reusable.
The demo site comes with a specific _include called interactive_metadata_table to help you make pages like this one complete with interactive DataTables and downloadable CSVs of collection metadata.
You can use GitHub actions or other CI to build your site automatically when you push to the repository and\or on a schedule. There are many other possibilities for creating content automatically based on web-events, and using staticman for forms that do more than just comments.
This is beyond the scope of a GitHub pages post, but I can’t help but adding a few links to indieweb. If you are publishing a personal blog, independent from an enterprise, then you are part of the indieweb.