erhant 0.1.9

My personal blog, hosted on docs.rs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

<!--
date: "2026-01-25"
tags: [rust]
title: "docs-r-us"
summary: "How this blog is hosted on docs.rs using Rust docstrings."
-->

# Blogging on docs.rs

One day I woke up and decided that my blog should live where my heart is: Rust docs. So here we are, unashamedly piggy-backing on [docs.rs](https://docs.rs).

## Why docs.rs?

- **Free hosting**: & its pretty cool tbh
- **Markdown-based**: Write in markdown, rendered beautifully
- **Version control**: Every version is preserved forever
- **Syntax highlighting**: All codeblocks are highlighted
- **Math rendering**: KaTeX support via custom header
- **Diagrams**: Mermaid.js for flowcharts and diagrams

## How It Works

The magic happens through Rust's documentation system. Each blog post is a markdown file that becomes a module's doc comment. Here's the flow:

```mermaid
flowchart TD
    subgraph src["src/blog/"]
        MD1["22-01-01_post-a.md"]
        MD2["23-05-15_post-b.md"]
        MD3["25-12-10_post-c.md"]
    end

    subgraph build["build.rs"]
        SCAN["Scan *.md files"]
        PARSE["Parse frontmatter"]
        SORT["Sort by date"]
        MERMAID["Transform mermaid blocks"]
        GEN["Generate modules & TOC"]
    end

    subgraph out["OUT_DIR"]
        TRANSFORMED["Transformed *.md"]
        BLOGPOSTS["blog_posts.rs"]
        TOC["blog_toc.md"]
    end

    subgraph output["Output"]
        DOCSRS["docs.rs/erhant"]
    end

    MD1 & MD2 & MD3 --> SCAN
    SCAN --> PARSE --> SORT --> MERMAID --> GEN
    MERMAID --> TRANSFORMED
    GEN --> BLOGPOSTS
    GEN --> TOC
    TRANSFORMED -.-> BLOGPOSTS
    BLOGPOSTS & TOC --> DOCSRS
```

### The Build Script

When you run `cargo build`, `build.rs` does all the heavy lifting:

1. **Scans** `src/blog/` for markdown files
2. **Parses** HTML-commented frontmatter for metadata (date, title, tags, summary)
3. **Sorts** posts by date, newest first
4. **Transforms** mermaid code blocks into HTML with Mermaid.js
5. **Generates** `blog_posts.rs` with module definitions
6. **Generates** `blog_toc.md` with a table of contents (titles linked to posts, with summaries)

The build script generates Rust code like this directly:

```rust
#[doc = "**Published:** 2025-01-01 | _rust_"]
#[doc = ""]
#[doc = include_str!("/path/to/transformed/post.md")]
pub mod hello_docsrs {}
```

A custom header enables KaTeX for math like $e^{i\pi} + 1 = 0$ and syntax highlighting for a variety of languages, including Solidity.

### Adding a New Post

1. Create `src/blog/YY-MM-DD_slug.md`
2. Add frontmatter:
   ```markdown
   <!--
   date: "YYYY-MM-DD"
   tags: [tag1, tag2]
   title: "Your Post Title"
   summary: "A brief one-sentence summary."
   -->
   ```
3. Write your content (mermaid diagrams just work)
4. Run `make build` to check everything works
5. Run `make docs` to actually view docs locally
6. Run `make publish` to publish new version

If you think this is cool or retarted, [leave a star](https://github.com/erhant/erhant)!