Codex

A minimal blog theme built for Hugo 🍜

• An about page 👋🏻 and a blog 📝
• Blog posts can be tagged 🏷
• Mathematical notations are supported with KaTex 📐
• Sass/SCSS for styling ✨
• Support for Google Analytics 📈 and Disqus 💬

Prerequisites

Hugo extended version (for Sass/SCSS support).

For macOS users, the extended version is installed by default if you use homebrew.

For Windows users, you can install with choco:

choco install hugo-extended -confirm

Getting started

At the root of your Hugo project, run:

git submodule add https://github.com/jakewies/hugo-theme-codex.git themes/codex

Next, copy the contents of the default config.toml to your site's config.toml. Make sure to read all the comments, as there a few nuances with Hugo themes that require some changes to that file.

Finally, run:

hugo server -D 

Note: If you are seeing a blank page it is probably because you have nothing in your content/ directory. Read on to fix that.

Configuring the Home Page

The site's home page can be configured by creating a content/_index.md file. This file can use the following frontmatter:

---
heading: "Hi, I'm Codex"
subheading: "A minimal blog theme for hugo."
handle: "hugo-theme-codex"
---

If you would rather override the about page's layout with your own, you can do so by creating a layouts/index.html. You can find the index.html file that hugo-theme-codex uses here.

Configuring Social Icons

Social Icons are optional. To show any of these icons, just provide the value in the [params] section of config.toml.

# config.toml

[params]
  twitter = "https://twitter.com/GoHugoIO"
  github = "https://github.com/jakewies/hugo-theme-codex"
  # ...

  iconTitles = ["Twitter", "GitHub"]

If any of these options are given, hugo-theme-codex will render the social icon in the footer, using the order specified in iconTitles.

See the contents of the example site for more details.

You can also create additional social icons by:

1. Add your own SVGs in static/icons/, for example static/icons/reddit.svg.
2. Modify your site's config as follows:

   [params]
      # ...
      reddit = "<url to your reddit>"
   
      iconTitles = [ "...", "Reddit"]
   

Make sure that the icon title must match the icon's file name. If the title contains more than one word, say "My Awesome Site", you can use dash "-" for the icon name: my-awesome-site.svg.

Creating a blog post

You can create a new blog post page by going to the root of your project and typing:

hugo new blog/:blog-post.md

Where :blog-post.md is the name of the file of your new post.

Optional parameters for your post, added by the theme:

• math:true enables math renderig with KaTeX
• toc: true adds a table of contents to your post

Adding a new section menu

In your site's config.toml, add a new menu definition for say, "photos":

# config.toml

[[menu.main]]
    identifier = "photos"
    name = "photos"
    title = "Photos"
    url = "/photos"

Then, put your posts under "content/photos".

Custom styling

In your site's folder, create assets/scss/custom.scss and put your custom styling there. For example, the snippet below changes the dot's color on your About page to blue:

// custom.scss
.fancy {
  color: #1e88e5;
}

You can even use Hugo variables/params in your custom styles too!

// custom.scss
.fancy {
  color: {{ .Site.Params.colors.fancy | default "#1e88e5" }}
}

# config.toml
[params.colors]
    fancy = "#f06292"

Tags

Right now hugo-theme-codex uses the tags taxonomy for blog posts. You can view all the blog posts of a given tag by going to /tags/:tag-name, where :tag-name is the name of your tag.

Favicon

To update favicon of the site, replace the one in static/favicon.ico with your own.

Contributing

Check out the CONTRIBUTORS.md file for more info on how you can contribute!

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Jake Wiesler 💻 🎨 📖

Chuxin Huang 📖 💻 🎨

Kent 💻 📖 🎨

Arushi Somani 📖

Xavier Valls 📖

This project follows the all-contributors specification. Contributions of any kind welcome!