FAQ

Common questions and answers about using Beautiful Jekyll

Remember: Beautiful Jekyll is built to be very customizable, and as such, many questions about “how do I change <…>?” can be answered by looking at the _config.yml file and modifying the settings there.


How do I add a favicon to my site?

Easy! Just place a valid favicon.ico in the root directory of your project. And then wait… It can take a while to update.

What’s the difference between the config file and the YAML parameters?

Great question! The config file is for site-wide settings, while the YAML parameters are added to each page individually and are applied on a per-page basis.

What if I want to use the same YAML parameter for all pages?

You can set default values for YAML parameters in the config file. Open the _config.yml file, scroll down to the line defaults: and that’s the section you can use. For more information, see the official jekyll documentation about default values.

Can I use Beautiful Jekyll as a “remote theme”?

Yes, you can! But I only recommend that to advanced users who can easily debug programming errors on their own. If that’s you, then check out the page dedicated to advanced installation methods.

How can I incorporate new features of Beautiful Jekyll into my old site?

Tip: Before updating your project, I recommend first reading through the What’s New page to see if there are any Breaking Changes that will affect you.

When a new version of Beautiful Jekyll is relased, your project won’t get the updates automatically. You’ll need to update your site to the latest version, and the steps to update depend on how you installed it (if you’re not sure which installation method you used, then it was probably “the easy way”).

If you installed “the easy way” (forking on GitHub):

You can follow GitHub’s instructions for synching a fork. In short, click the Sync fork button, and then the Update branch button. This will bring all the updates from Beautiful Jekyll into your site.

If after clicking Sync fork you don’t see an Update branch button, it means that GitHub is not able to automatically bring in the updates. This can happen if you made changes to a file that was also updated in Beautiful Jekyll - usually the _config.yml file. If that happens, then my suggested workflow is to delete your current GitHub project and start fresh: (1) make a copy of any files that you modified/created (usually this means the _config.yml file, all blog posts, and any additional pages you created), (2) delete your project on GitHub, (3) re-fork Beautiful Jekyll, (4) add all the content you previously created. Since this is cumbersome, you might want to attempt the more advanced installation methods that make updating easier.

If you installed as a “remote theme” or using Ruby:

Updating to the latest version only requires you to change the version in the config file or the Gemfile. For example, if the latest version is “5.0.0”, then change remote_theme: daattali/beautiful-jekyll@4.0.0 to remote_theme: daattali/beautiful-jekyll@5.0.0).

How do I make small modifications to how my website looks?

If you want to make any visual changes that are not in _config.yml, you’ll need to add your own CSS rules to the file assets/css/custom-styles.css and enable the site-css setting in the config file. This will allow you to overwrite the default Beautiful Jekyll styles. If you don’t know how to use CSS, I highly recommend spending 30 minutes to learn the basics.

How do I use a custom domain for my site?

GitHub lets you have your website for free using their github.io domain. If you want your own domain (such as https://myname.com), it’s easy and will cost about $10-$15 per year. First you need to buy a domain name (I recommend Namecheap) and then follow the instructions GitHub provides.

What if I want a free domain, but not https://YOURUSERNAME.github.io?

Every GitHub user can have one single repository (repository = project) named YOURUSERNAME.github.io and the website for that repository will be https://YOURUSERNAME.github.io. This is called a user site.

If you want your project to be named something else, for example MyAwesomeProject, that’s no problem! All you have to do is go to Settings at the top right corner of the page, and rename your repository to MyAwesomeProject (remember to click on the Rename button to confirm!). Then you need to enable GitHub Pages (automatic website building) by clicking on the Pages tab on the left side, selecting “master” or “main” in the Branch section, and clicking Save.

Now your website will be at https://YOURUSERNAME.github.io/MyAwesomeProject. This is called a project site. Make sure to read the next question about using images in project sites.

Why do images or links not work in my project site?

This issue is only applicable to project sites on GitHub Pages, for example https://USERNAME.github.io/MyProject.

URLs that begin with / and refer to local files may not work correctly in project sites due to how the root URL (/) is interpreted by GitHub Pages. For example, you may have a link in markdown such as [page5](/page5) that you want to link to https://USERNAME.github.io/MyProject/page5, but instead it links to https://USERNAME.github.io/page5. Similarly, you may have an image such as ![](/assets/img/pic.jpg) that doesn’t work because it tries to grab the image from https://USERNAME.github.io/assets/img/pic.jpg instead of from https://USERNAME.github.io/MyProject/assets/img/pic.jpg.

One solution to this is to fix the URL by adding your project’s name, for example [page5](/page5) should become [page5](/MyProject/page5). Another solution that I recommend is to use a jekyll feature called relative_url, which automatically adds the project name to URLs. To fix the above examples, [page5](/page5) should change to [page5]({{ '/page5' | relative_url }}) and ![](/assets/img/pic.jpg) would change to ![]({{ '/assets/img/pic.jpg' | relative_url }}) .

Note that any URL in the frontend YAML already does this automatically, so this is only required for URLs within your page content.

How do I move the blog to another page instead of having it on the home page?

The default style of Beautiful Jekyll is to feature the blog feed on the front page. For some sites that’s not the ideal structure, and you may want to have a separate dedicated page for the blog posts. To have the blog hosted on a different URL (for example at <mysite.com>/blog), copy the index.html file into a folder with the same name as the desired page (for example, to blog/index.html), and in the _config.yml file you need to add a setting paginate_path: "/<page name>/page:num/" (for example paginate_path: "/blog/page:num/").

How do I use math equations in my posts?

Use the mathjax: true YAML parameter on any page to be able to use MathJax. Note that in MathJax you need to use $$ and \\( to start/end expressions (as opposed to $ and \( in LaTeX). If you want to configure MathJax differently than the default configuration, you may edit the file _includes/mathjax.html.

I want to remove the “Powered by …” notice at the bottom

To remove the ad, you need to upgrade your plan.

How do I change the colour scheme to a dark theme?

To unlock this feature, and other features, you need to upgrade your plan.

I really like Beautiful Jekyll, how can I help?

Thank you for asking!

Continuously developing and maintaining this theme is not a simple job, so any level of support would be greatly appreciated!

I have a different question

Beautiful Jekyll is a Jekyll theme, so many questions can be answered by searching Google, the Jekyll documentation, or the Jekyll support forum.

If you have a specific question about using Beautiful Jekyll or need help, you can always attend the office hours, which is open to sponsors. You can also try the Discussions area to try to get help from the community.