We use cookies on this site to enhance your user experience
By clicking the Accept button, you agree to us doing so. More info on our cookie policy
We use cookies on this site to enhance your user experience
By clicking the Accept button, you agree to us doing so. More info on our cookie policy
Published: May 8, 2020 by C.S. Rhymes
I created Bulma Clean Theme as a theme for my own website and decided to open source it so others could use it as well. One of the key things I wanted to do was to create a theme that worked with GitHub Pages, which also means that you can also use it as a docs site for your project.
GitHub pages allows you to create a website for your project with free hosting. Go to your repo on GitHub, then click Settings, then scroll down to the GitHub Pages section. You have the option to create a site from the root of your master branch of from the /docs directory in your master branch. For this example, we are going to use the /docs directory.
Don’t change this setting just yet as if you don’t have a docs directory there will be nothing there to publish.
Clone your git repo to a local directory, let’s say ~/code/my-project
for this example. The below assumes you don’t yet have a docs directory and you have jekyll installed. If you do already have a docs directory you will have to rename it to something else.
Create a new jekyll installation in the docs directory, ensuring you replace your username and project name in the below example.
git clone https://github.com/username/my-project.git ~/code/my-project
cd ~/code/my-project
jekyll new docs
You should now have a base install of Jekyll in your freshly created docs directory.
source 'https://rubygems.org'
gem "bulma-clean-theme", '0.7.2'
gem 'github-pages', group: :jekyll_plugins
_config.yml
and comment out or delete the line theme: minima
and replace it with remote_theme: chrisrhymes/bulma-clean-theme
, then add github-pages
to the list of plugins. Update the baseurl to your GitHub repo name, in this example we are using my-project
as the repo name
#theme: minima
remote_theme: chrisrhymes/bulma-clean-theme
baseurl: "/my-project"
plugins:
- github-pages
index.md
file and update the front matter so the layout is page and then add a title
layout: page
title: Docs for My Project
Run bundle install
and then bundle exec jekyll serve
http://localhost:4000/my-project/
to view your new docs page.To create a menu on the left on your docs page you need to create a new yaml file in _data directory, such as menu.yaml
and then use the below format, where the label will be the menu title and the items are the menu items. Each menu item can have a list of sub menu items if needed.
- label: Example Menu
items:
- name: Menu item
link: /link/
items:
- name: Sub menu item
link: /sub-menu-item/
If you would like auto generated table of contents for your docs page then add toc: true
to the page’s front matter. The table of contents works for markdown pages and loops through the heading 2s and heading 3s in the markdown and then auto generates the contents.
If you want to link to your GitHub sponsors profile then add gh_sponsor
with your username to the _config.yml
file.
gh_sponsor: chrisrhymes
Once you have finished creating your docs page you can commit your changes and push everything up to GitHub. Go back to the GitHub settings page and scroll back down to the GitHub Pages section. Now we can update the setting to use the Master branch /docs folder and then GitHub will build your new docs page.
I recently updated one of my own packages to use Bulma Clean Theme to power the docs page. Check out the docs for Bulma Block List as an example.
Share
Latest Posts
I have seen a lot of threads from indie authors asking for advice with marketing their ebook. If I’m honest, I have never really had a strategy for marketing my books, I just assumed that I could put it out there and people would find it. In the real world, that does not seem to be the case.
This post follows on from my last post about using your website to promote your ebooks. The first step of the article explains that you need to make a website, but didn’t go into too much detail. This post aims at explaining how you can build a landing page for your book with Bulma Clean Theme.
I’m a web developer by trade and a part-time author, so here are a few things that I have done to help promote my books and ebooks using my website and my tech know how from my day job.