first commit
This commit is contained in:
bs-sensei
384
README.md
Normal file
384
README.md
Normal file
@@ -0,0 +1,384 @@
|
||||
# Codex Obscura
|
||||
|
||||
> *A dark academia pixel Hugo theme with a fall color palette.*
|
||||
>
|
||||
> Candlelit manuscripts meet cozy stationery. Books, tea, fountain pens, and the quiet rustle of digital marginalia.
|
||||
|
||||
---
|
||||
|
||||
```
|
||||
██████╗ ██████╗ ██████╗ ███████╗██╗ ██╗
|
||||
██╔════╝██╔═══██╗██╔══██╗██╔════╝╚██╗██╔╝
|
||||
██║ ██║ ██║██║ ██║█████╗ ╚███╔╝
|
||||
██║ ██║ ██║██║ ██║██╔══╝ ██╔██╗
|
||||
╚██████╗╚██████╔╝██████╔╝███████╗██╔╝ ██╗
|
||||
╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- **Fall color palette** — deep ambers, burnt orange, rust, forest green, umber, parchment cream
|
||||
- **Pixel art borders** — CSS-only pixel-perfect box shadow borders on all cards and widgets
|
||||
- **Blinking `█` cursor** in the site title (optional, easily disabled)
|
||||
- **Dark academia typography** — VT323 (pixel/terminal) for headings + Josefin Sans for body text
|
||||
- **Dust mote ambient animation** — soft floating particles that drift across the page like dust in a library
|
||||
- **Sidebar** — sys-info widget with live uptime counter, recent posts, tag cloud, and optional marginalia quote
|
||||
- **Year-grouped archive** — posts grouped by year in terminal `ls -la` style
|
||||
- **Tag filtering** — clickable tag chips at the top of the archive page with active highlighting
|
||||
- **Post subtitles** — optional per-post tagline shown on cards and single pages
|
||||
- **Responsive (Mostly)** — two-column desktop, stacked mobile
|
||||
- **RSS feed** — full RSS out of the box
|
||||
- **SEO-ready** — Open Graph, Twitter Card, canonical URLs
|
||||
- **Syntax highlighting** — via highlight.js with Common Lisp support, add more lines to layout/partials/head.html for more
|
||||
- **LaTeX rendering** — via KaTeX with Hugo passthrough for clean math expressions
|
||||
- **Custom code blocks** — shortcode with language label and optional title
|
||||
- **Comments** — Comentario integration (self-hosted, privacy-focused)
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### As a Git Submodule (recommended)
|
||||
|
||||
First run `hugo new site <sitename>`
|
||||
|
||||
```bash
|
||||
cd <sitename>
|
||||
git submodule add https://git.johnabs.xyz/bs-sensei/codex-obscura-hugo-theme
|
||||
```
|
||||
|
||||
### Manual
|
||||
|
||||
Download and place the folder at `themes/codex-obscura/` inside your Hugo site, which you should have made using `hugo new site <sitename>`
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
After creating your site at <sitename> from above and adding the template, you should first go to the `content` folder and create an about.md, resume.md, and a donate.md in your content folder or these will redirect to "Not Found". Your posts link will also redirect, unless you make a folder within content called `posts` and make `post1.md` inside it and add some text. Examples of each of these are provided below for your convenience.
|
||||
|
||||
A full `hugo.toml` example:
|
||||
|
||||
```toml
|
||||
baseURL = "https://yourdomain.com/"
|
||||
languageCode = "en-us"
|
||||
title = "Your Site Title"
|
||||
theme = "codex-obscura"
|
||||
paginate = 8
|
||||
summaryLength = 20
|
||||
|
||||
[markup.highlight]
|
||||
codeFences = false # disable Chroma — we use highlight.js instead
|
||||
|
||||
[markup.goldmark.renderer]
|
||||
unsafe = true # you can probably set this to false, try both. False works for me :)
|
||||
|
||||
[markup.goldmark.extensions.passthrough]
|
||||
enable = true
|
||||
[markup.goldmark.extensions.passthrough.delimiters]
|
||||
block = [["$$", "$$"]]
|
||||
inline = [["$", "$"]]
|
||||
|
||||
[params]
|
||||
description = "Your site description shown in the hero card."
|
||||
author = "Your Name"
|
||||
tagline = "a brief italicized tagline"
|
||||
sidebarQuote = "A quote you love."
|
||||
sidebarQuoteAuthor = "The Author"
|
||||
resumePDF = "/files/resume.pdf"
|
||||
comentarioURL = "https://comments.yourdomain.com"
|
||||
|
||||
[params.social]
|
||||
github = "yourusername"
|
||||
mastodon = "https://mastodon.social/@you"
|
||||
email = "you@example.com"
|
||||
|
||||
[[menu.main]]
|
||||
name = "home"
|
||||
url = "/"
|
||||
weight = 1
|
||||
[[menu.main]]
|
||||
name = "posts"
|
||||
url = "/posts/"
|
||||
weight = 2
|
||||
[[menu.main]]
|
||||
name = "tags"
|
||||
url = "/tags/"
|
||||
weight = 3
|
||||
[[menu.main]]
|
||||
name = "about"
|
||||
url = "/about/"
|
||||
weight = 4
|
||||
[[menu.main]]
|
||||
name = "resume"
|
||||
url = "/resume/"
|
||||
weight = 5
|
||||
[[menu.main]]
|
||||
name = "donate"
|
||||
url = "/donate/"
|
||||
weight = 6
|
||||
|
||||
[taxonomies]
|
||||
tag = "tags"
|
||||
category = "categories"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Creating Content
|
||||
|
||||
```bash
|
||||
# New blog post
|
||||
hugo new posts/my-entry.md
|
||||
|
||||
# New about page
|
||||
hugo new about.md
|
||||
```
|
||||
|
||||
### Post front matter
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "My Entry"
|
||||
date: 2024-10-31
|
||||
draft: false
|
||||
description: "A brief description shown in meta tags."
|
||||
summary: "Optional hand-written summary overriding auto-generation."
|
||||
subtitle: "a quiet meditation on autumn leaves"
|
||||
tags: ["autumn", "philosophy", "notes"]
|
||||
author: "Archivist"
|
||||
featured: true # pins to homepage
|
||||
nocomments: true # disables comments on this post
|
||||
---
|
||||
```
|
||||
|
||||
The `<!--more-->` divider can be placed anywhere in the body to manually control where the summary cuts off:
|
||||
|
||||
```markdown
|
||||
This sentence will appear as the summary.
|
||||
|
||||
<!--more-->
|
||||
|
||||
The rest of the post continues here.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Special Pages
|
||||
|
||||
### About
|
||||
|
||||
Create `content/about.md` with any content. Hugo uses `_default/single.html`.
|
||||
|
||||
### Resume
|
||||
|
||||
Create `content/resume.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Resume"
|
||||
type: "resume"
|
||||
layout: "single"
|
||||
resumeName: "Your Name"
|
||||
resumeTitle: "Your subtitle"
|
||||
email: "you@example.com"
|
||||
location: "somewhere cozy"
|
||||
website: "https://yoursite.com"
|
||||
github: "yourusername"
|
||||
resumePDF: "/files/resume.pdf"
|
||||
_build:
|
||||
list: never
|
||||
---
|
||||
```
|
||||
|
||||
Use `##` for sections, `###` for job/entry titles, `####` for subtitle/date lines. Place your PDF at `static/files/resume.pdf`.
|
||||
|
||||
### Donate
|
||||
|
||||
Create `content/donate.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Support"
|
||||
type: "donate"
|
||||
layout: "single"
|
||||
_build:
|
||||
list: never
|
||||
kofi: "yourusername"
|
||||
liberapay: "yourusername"
|
||||
github_sponsors: "yourusername"
|
||||
bitcoin: "bc1qyouraddress"
|
||||
ethereum: "0xyouraddress"
|
||||
monero: "4youraddress"
|
||||
litecoin: "ltc1youraddress"
|
||||
---
|
||||
```
|
||||
|
||||
Crypto wallet cards include QR codes generated client-side in the site's amber color palette. Remove any platforms you don't use and they won't appear.
|
||||
|
||||
---
|
||||
|
||||
## Syntax Highlighting
|
||||
|
||||
The theme uses **highlight.js** instead of Hugo's built-in Chroma for better Common Lisp support as it's my preferred language.
|
||||
This is already added to `layouts/partials/head.html`, and more can be added as you go as shown below:
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/base16/monokai.min.css">
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.common.min.js"></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/lisp.min.js"></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/python.min.js"></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/r.min.js"></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/julia.min.js"></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/bash.min.js"></script>
|
||||
<script>
|
||||
hljs.highlightAll();
|
||||
</script>
|
||||
```
|
||||
|
||||
### Custom code block shortcode
|
||||
|
||||
Create `layouts/shortcodes/code.html` in your site root (this one you need to do!! I can't do it for you in advance):
|
||||
|
||||
```html
|
||||
<div class="code-block">
|
||||
{{- with .Get "lang" }}
|
||||
<div class="code-block__header">
|
||||
<span class="code-block__lang">{{ . }}</span>
|
||||
{{- with $.Get "title" }}
|
||||
<span class="code-block__title">{{ . }}</span>
|
||||
{{- end }}
|
||||
</div>
|
||||
{{- end }}
|
||||
<div class="code-block__body">
|
||||
{{ highlight (trim .Inner "\n") (.Get "lang" | default "text") "" }}
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
Use it in posts:
|
||||
|
||||
```
|
||||
{{< code lang="python" title="fibonacci.py" >}}
|
||||
def fib(n):
|
||||
return n if n < 2 else fib(n-1) + fib(n-2)
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## LaTeX
|
||||
|
||||
I added KaTeX to `layouts/partials/head.html` for math typesetting:
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css">
|
||||
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"></script>
|
||||
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js"
|
||||
onload="renderMathInElement(document.body, {
|
||||
delimiters: [
|
||||
{left: '$$', right: '$$', display: true},
|
||||
{left: '$', right: '$', display: false}
|
||||
]
|
||||
});">
|
||||
</script>
|
||||
```
|
||||
|
||||
Then write inline math with `$x^2$` and display math with `$$\int_0^\infty e^{-x}dx$$`.
|
||||
|
||||
---
|
||||
|
||||
## Comments (Comentario)
|
||||
|
||||
Install and run a [Comentario](https://gitlab.com/comentario/comentario) instance, then add to `hugo.toml`:
|
||||
|
||||
```toml
|
||||
[params]
|
||||
comentarioURL = "https://comments.yourdomain.com"
|
||||
```
|
||||
|
||||
Comments appear automatically on all posts. Disable per-post with `nocomments: true` in front matter.
|
||||
|
||||
---
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Variable | Value | Use |
|
||||
|--------------------|-----------|------------------------|
|
||||
| `--amber` | `#d4a228` | Primary accent |
|
||||
| `--orange` | `#c4601c` | Secondary accent |
|
||||
| `--rust` | `#8a2e08` | Deep accent |
|
||||
| `--forest-light` | `#4e7830` | Terminal prompt green |
|
||||
| `--text-parchment` | `#e8d5a3` | Primary text |
|
||||
| `--bg-primary` | `#130e07` | Main background |
|
||||
| `--bg-secondary` | `#1c1509` | Card backgrounds |
|
||||
|
||||
Override any variable by adding a `static/css/custom.css` and referencing it in `hugo.toml`:
|
||||
|
||||
```toml
|
||||
[params]
|
||||
customCSS = ["css/custom.css"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Role | Font | Notes |
|
||||
|----------|--------------|-----------------------------|
|
||||
| Terminal | VT323 | Headings, nav, UI elements |
|
||||
| Body | Josefin Sans | Paragraph text, sans-serif |
|
||||
| Code | Courier Prime| Code blocks, monospace |
|
||||
|
||||
All loaded from Google Fonts.
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
codex-obscura/
|
||||
├── archetypes/
|
||||
│ └── default.md
|
||||
├── exampleSite/
|
||||
│ ├── hugo.toml
|
||||
│ └── content/
|
||||
│ ├── resume.md
|
||||
│ └── donate.md
|
||||
├── layouts/
|
||||
│ ├── index.html # Homepage
|
||||
│ ├── _default/
|
||||
│ │ ├── baseof.html
|
||||
│ │ ├── single.html # Single post
|
||||
│ │ └── list.html # Archive / tag pages
|
||||
│ ├── resume/
|
||||
│ │ └── single.html # Resume page
|
||||
│ ├── donate/
|
||||
│ │ └── single.html # Donate page with QR codes
|
||||
│ ├── tags/
|
||||
│ │ └── terms.html # Tag index
|
||||
│ └── partials/
|
||||
│ ├── head.html
|
||||
│ ├── header.html
|
||||
│ ├── footer.html
|
||||
│ ├── sidebar.html
|
||||
│ └── comments.html # Comentario integration
|
||||
├── static/
|
||||
│ ├── css/main.css
|
||||
│ ├── js/main.js # Dust mote animation
|
||||
│ └── favicon.svg
|
||||
├── theme.toml
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT — Please attribute my work to me!
|
||||
|
||||
---
|
||||
|
||||
*"The library is infinite and the lights are always low."*
|
||||
Reference in New Issue
Block a user