ceda_ei
/
cedaei.com
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
cedaei.com/README.md

254 lines
13 KiB
Markdown
Raw Blame History

## Codex
A minimal blog theme built for [Hugo](https://gohugo.io/) 🍜
![Hugo desktop screenshot](/images/screenshot.png)
- 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:
```bash
git submodule add https://github.com/jakewies/hugo-theme-codex.git themes/hugo-theme-codex
```
Next, copy the contents of the [`exampleSite/config.toml`](https://github.com/jakewies/hugo-theme-codex/blob/master/exampleSite/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.
The most important change you will need to make to the `config.toml` is removing [this line](https://github.com/jakewies/hugo-theme-codex/blob/master/exampleSite/config.toml#L2):
```
themesDir = "../../"
```
It only exists in the example site so that the demo can function properly.
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:
```md
---
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](https://github.com/jakewies/hugo-theme-codex/blob/master/layouts/index.html).
### Configuring Social Icons
Social Icons are optional. To show any of these icons, just provide the value in the `[params]` section of `config.toml`.
```toml
# config.toml
[params]
twitter = "https://twitter.com/GoHugoIO"
github = "https://github.com/jakewies/hugo-theme-codex"
# ...
iconOrder = ["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 `iconOrder`.
See the contents of the [example site](https://github.com/jakewies/hugo-theme-codex/tree/master/exampleSite) for more details.
You can also create additional social icons by:
1. Adding your own SVGs in `static/svg/`, for example `static/svg/reddit.svg`.
2. Modifying your site's config as follows:
```toml
[params]
# ...
reddit = "<url to your reddit>"
iconOrder = ["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.
This will execute the theme's `blog` archetype to create a new markdown file in `contents/blog/:blog-post.md` with the following frontmatter:
```md
# Default post frontmatter:
# The title of your post. Default value is generated
# From the markdown filename
title: "{{ replace .TranslationBaseName "-" " " | title }}"
# The date the post was created
date: {{ .Date }}
# The post filename
slug: ""
# Post description used for seo
description: ""
# Post keywords used for seo
keywords: []
# If true, the blog post will not be included in static build
draft: true
# Categorize your post with tags
tags: []
# Uses math typesetting
math: false
# Includes a table of contents on screens >1024px
toc: false
```
The frontmatter above is the default for a new post, but all values can be changed.
### Configuring Table of Contents in blog posts
To display post title in Table of Contents in blog posts, set `showPageTitleInTOC`
to `true` in the `[params]` section of `config.toml`.
```toml
# config.toml
[params]
# ...
showPageTitleInTOC = true
```
### Adding a new section menu
In your site's `config.toml`, add a new menu definition for say, "photos":
```toml
# config.toml
[[menu.main]]
identifier = "photos"
name = "photos"
title = "Photos"
url = "/photos"
```
Then, put your posts under "content/photos".
### Custom styling
You have two options for custom styling. The first is to create an `assets/scss/custom.scss` in your project and put your custom styling there. For example, the snippet below changes the dot's color on your About page to blue:
```scss
// custom.scss
.fancy {
color: #1e88e5;
}
```
You can even use Hugo variables/params in your custom styles too!
```scss
// custom.scss
.fancy {
color: {{ .Site.Params.colors.fancy | default "#1e88e5" }}
}
```
```toml
# config.toml
[params.colors]
fancy = "#f06292"
```
The second option is to use the supported scss overrides. You can do this by creating an `assets/scss/overrides/scss` file in your project. The following overrides are supported:
```scss
// overrides.scss
// The primary accent color used throughout the site
$primary: ''
```
### 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](https://github.com/jakewies/hugo-theme-codex/blob/master/CONTRIBUTING.md) for more info on how you can contribute!
## Contributors ✨
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[![All Contributors](https://img.shields.io/badge/all_contributors-19-orange.svg?style=flat-square)](#contributors-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tr>
<td align="center"><a href="https://www.jakewiesler.com"><img src="https://avatars1.githubusercontent.com/u/12075916?v=4" width="100px;" alt=""/><br /><sub><b>Jake Wiesler</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=jakewies" title="Code">💻</a> <a href="#design-jakewies" title="Design">🎨</a> <a href="https://github.com/jakewies/hugo-theme-codex/commits?author=jakewies" title="Documentation">📖</a></td>
<td align="center"><a href="https://www.chuxinhuang.com/"><img src="https://avatars2.githubusercontent.com/u/30974572?v=4" width="100px;" alt=""/><br /><sub><b>Chuxin Huang</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=chuxinh" title="Documentation">📖</a> <a href="https://github.com/jakewies/hugo-theme-codex/commits?author=chuxinh" title="Code">💻</a> <a href="#design-chuxinh" title="Design">🎨</a></td>
<td align="center"><a href="https://kentnek.com"><img src="https://avatars1.githubusercontent.com/u/7024160?v=4" width="100px;" alt=""/><br /><sub><b>Kent</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=kentnek" title="Code">💻</a> <a href="https://github.com/jakewies/hugo-theme-codex/commits?author=kentnek" title="Documentation">📖</a> <a href="#design-kentnek" title="Design">🎨</a></td>
<td align="center"><a href="https://github.com/somaniarushi"><img src="https://avatars3.githubusercontent.com/u/54224195?v=4" width="100px;" alt=""/><br /><sub><b>Arushi Somani</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=somaniarushi" title="Documentation">📖</a></td>
<td align="center"><a href="https://github.com/xvallspl"><img src="https://avatars0.githubusercontent.com/u/867299?v=4" width="100px;" alt=""/><br /><sub><b>Xavier Valls</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=xvallspl" title="Documentation">📖</a> <a href="https://github.com/jakewies/hugo-theme-codex/commits?author=xvallspl" title="Code">💻</a> <a href="#design-xvallspl" title="Design">🎨</a></td>
<td align="center"><a href="https://github.com/pyvain"><img src="https://avatars3.githubusercontent.com/u/2924494?v=4" width="100px;" alt=""/><br /><sub><b>Pyvain</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=pyvain" title="Code">💻</a> <a href="https://github.com/jakewies/hugo-theme-codex/commits?author=pyvain" title="Documentation">📖</a></td>
<td align="center"><a href="http://jlebar.com"><img src="https://avatars1.githubusercontent.com/u/150663?v=4" width="100px;" alt=""/><br /><sub><b>Justin Lebar</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=jlebar" title="Code">💻</a></td>
</tr>
<tr>
<td align="center"><a href="https://www.aareet.com"><img src="https://avatars1.githubusercontent.com/u/33654?v=4" width="100px;" alt=""/><br /><sub><b>Aareet Shermon</b></sub></a><br /><a href="#design-aareet" title="Design">🎨</a></td>
<td align="center"><a href="https://github.com/dgnicholson"><img src="https://avatars1.githubusercontent.com/u/6208288?v=4" width="100px;" alt=""/><br /><sub><b>dgnicholson</b></sub></a><br /><a href="#design-dgnicholson" title="Design">🎨</a> <a href="https://github.com/jakewies/hugo-theme-codex/commits?author=dgnicholson" title="Code">💻</a></td>
<td align="center"><a href="https://msfjarvis.dev"><img src="https://avatars0.githubusercontent.com/u/13348378?v=4" width="100px;" alt=""/><br /><sub><b>Harsh Shandilya</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=msfjarvis" title="Code">💻</a></td>
<td align="center"><a href="https://twitter.com/ProfessorLogout"><img src="https://avatars3.githubusercontent.com/u/13572444?v=4" width="100px;" alt=""/><br /><sub><b>Marco Kamner</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=ProfessorLogout" title="Code">💻</a></td>
<td align="center"><a href="https://ewen.io/"><img src="https://avatars3.githubusercontent.com/u/10872821?v=4" width="100px;" alt=""/><br /><sub><b>ewen</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=ewenme" title="Code">💻</a></td>
<td align="center"><a href="https://github.com/SanchithHegde"><img src="https://avatars2.githubusercontent.com/u/22217505?v=4" width="100px;" alt=""/><br /><sub><b>Sanchith Hegde</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=SanchithHegde" title="Code">💻</a> <a href="https://github.com/jakewies/hugo-theme-codex/commits?author=SanchithHegde" title="Documentation">📖</a></td>
<td align="center"><a href="https://soeren.codes"><img src="https://avatars1.githubusercontent.com/u/5760400?v=4" width="100px;" alt=""/><br /><sub><b>Sören Johanson</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=CER10TY" title="Code">💻</a></td>
</tr>
<tr>
<td align="center"><a href="https://github.com/jdl031"><img src="https://avatars3.githubusercontent.com/u/1720477?v=4" width="100px;" alt=""/><br /><sub><b>James Lloyd</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=jdl031" title="Code">💻</a></td>
<td align="center"><a href="http://wilsonehusin.com"><img src="https://avatars1.githubusercontent.com/u/14004487?v=4" width="100px;" alt=""/><br /><sub><b>Wilson E. Husin</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=wilsonehusin" title="Code">💻</a></td>
<td align="center"><a href="https://tommorris.org/"><img src="https://avatars0.githubusercontent.com/u/175?v=4" width="100px;" alt=""/><br /><sub><b>Tom Morris</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=tommorris" title="Code">💻</a></td>
<td align="center"><a href="http://twitter.com/sdil"><img src="https://avatars0.githubusercontent.com/u/461537?v=4" width="100px;" alt=""/><br /><sub><b>Mohamad Fadhil</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=sdil" title="Code">💻</a></td>
<td align="center"><a href="https://github.com/skvale"><img src="https://avatars0.githubusercontent.com/u/5314713?v=4" width="100px;" alt=""/><br /><sub><b>Sam Kvale</b></sub></a><br /><a href="https://github.com/jakewies/hugo-theme-codex/commits?author=skvale" title="Code">💻</a></td>
</tr>
</table>
<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
Reference in New Issue View Git Blame Copy Permalink