# 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."*