How to set up a simple static markdown-based blog for a personal journey diary and more?
Let s start with Hugo, which provides a command-line tool for creating and setting up a blog based on markdown files.
The Hugo quick-start guide provides the base information to get started, just follow it.
My exceptions to the quick-start guide
- In my case, I went for the git installation by compiling the tool to get the needed version I wanted to have for my arch system.
- I cloned the theme into the ‘./themes/xyz’ subfolder and version it myself now. Therefore I can more easily make changes to the theme as needed but loose compatibility with the original theme.
With the base setup for the quick-start guide, you are good to go for adding content and testing it locally. Further, creating additional pages with content such as ‘about’ or a ‘CV’ is possible.
Important: if you have changed the configuration
baseurl, it happens that the content is not correctly visible via the browser http://localhost:1313, because the browser tries to fetch the style and more from the given base URL.
Hosting on GitLab
Next on the list is the hosting and building on GitLab. Therefore, set up a GitLab project and prepare the project locally. The Host on GitLab guide provides the base steps from activating the GitLab CI for building and the hosting via a GitLab Page.
My exceptions to the Host on Gitlab guide
- Since I use a specific Hugo version with extensions, I also need that version for the CI builds. So, go to the GitLab Hugo registry and search for the correct version you want to use.
GitLab will automatically detect the .gitlab-ci.yml file and start building the web page and deploying it to the following public path: https://<YourUsername>.gitlab.io/<your-hugo-site>/.
After the pipeline went through without any error, there will be not a lot visible in the browser unless you updated the baseurl from before in the config.toml.
Make sure your
baseURLkey-value in your site configuration reflects the full URL of your GitLab pages repository if you’re using the default GitLab Pages URL (e.g.,
https://<YourUsername>.gitlab.io/<your-hugo-site>/) and not a custom domain.
Custom URL and TLS/SSL (only if you own a domain and can change the DNS records)
Yes, GitLab Pages support custom URLs, including a TLS/SSL certificate if you own a domain. In my case, I dedicate the domain blog.dbaumi.at for this purpose.
First, in your GitLab project, go to Settings > Pages > New Domain. Enter your custom domain and check that the Let’s Encrypt setting is active. Next, all the required steps and records should be visible in the next view. Go to your DNS server, set up the A or CNAME record for the domain, and add the TXT setting for the owning verification. Additionally, GitLab provides a setting that redirects HTTP to HTTPS. Check out the Settings > Pages > Force HTTPS.
Enjoy your new blog automation served via GitLab with a custom Domain and TLS/SSL certificate.