Skip to content

Commit 2ccd55d

Browse files
corylanoucorylanou
committed
feat: add X/Twitter link to nav and first blog post
Add hype_markdown X account link to header and footer navigation. Add first blog post: single-source documentation workflow tutorial.
1 parent c2c5be1 commit 2ccd55d

3 files changed

Lines changed: 141 additions & 0 deletions

File tree

‎content/single-source-docs/module.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Single-Source Documentation: One Markdown File for Your README and Website
2+
3+
<details>
4+
slug: single-source-docs
5+
published: 03/15/2026
6+
author: Cory LaNou
7+
seo_description: Learn how to use Hype to maintain a single Markdown source that generates both your GitHub README and website documentation, keeping them permanently in sync.
8+
tags: tutorial, docs, workflow, hype
9+
</details>
10+
11+
Every open source project has the same problem: documentation lives in too many places. Your README says one thing, your docs site says another, and the install instructions in your wiki are three versions behind. You end up maintaining the same content in multiple locations, and they inevitably drift apart.
12+
13+
Hype solves this by letting you write your documentation once and generate multiple outputs from a single source.
14+
15+
## The Problem
16+
17+
A typical project has documentation scattered across:
18+
19+
- `README.md` in the repo root
20+
- A docs site (GitHub Pages, Netlify, etc.)
21+
- Wiki pages
22+
- Blog posts or tutorials
23+
24+
When you update an API or change an install command, you have to remember to update every copy. You won't. Nobody does.
25+
26+
## The Hype Approach
27+
28+
With Hype, you write a single `hype.md` file that includes source files, executes code, and validates everything at build time. Then you generate your README from it:
29+
30+
```bash
31+
hype export -format markdown -f hype.md > README.md
32+
```
33+
34+
Your README is now a build artifact, not a hand-maintained file. Change the source, regenerate, and every output stays in sync.
35+
36+
## A Practical Example
37+
38+
Let's say you're building a Go CLI tool. Your documentation needs to show:
39+
40+
1. How to install it
41+
2. A code example
42+
3. The command's help output
43+
44+
### Step 1: Create Your Source File
45+
46+
Create a `hype.md` at the root of your project:
47+
48+
```markdown
49+
# My CLI Tool
50+
51+
A fast and simple tool for doing things.
52+
53+
## Installation
54+
55+
&#96;&#96;&#96;bash
56+
go install github.com/you/tool@latest
57+
&#96;&#96;&#96;
58+
59+
## Quick Example
60+
61+
&lt;code src="examples/hello/main.go"&gt;&lt;/code&gt;
62+
63+
## Usage
64+
65+
&lt;cmd exec="go run ./cmd/tool -h"&gt;&lt;/cmd&gt;
66+
```
67+
68+
The `<code>` tag includes your actual source file. The `<cmd>` tag runs a command and captures the output. Both happen at build time.
69+
70+
### Step 2: Generate Your README
71+
72+
```bash
73+
hype export -format markdown -f hype.md > README.md
74+
```
75+
76+
The generated README contains the actual contents of `examples/hello/main.go` and the real output of `go run ./cmd/tool -h`. If either changes, the next build picks it up automatically.
77+
78+
### Step 3: Automate It
79+
80+
Add a CI step so the README regenerates on every push. The Hype repo itself does exactly this — a GitHub Actions workflow runs `hype export` and commits the updated README if it changed.
81+
82+
Here's a minimal workflow:
83+
84+
```yaml
85+
name: Generate README
86+
on:
87+
push:
88+
branches: [main]
89+
90+
jobs:
91+
readme:
92+
runs-on: ubuntu-latest
93+
steps:
94+
- uses: actions/checkout@v4
95+
- uses: actions/setup-go@v5
96+
with:
97+
go-version-file: go.mod
98+
- run: go install github.com/gopherguides/hype/cmd/hype@latest
99+
- run: hype export -format markdown -f hype.md > README.md
100+
- name: Commit if changed
101+
run: |
102+
git config user.name "github-actions[bot]"
103+
git config user.email "github-actions[bot]@users.noreply.github.com"
104+
git add README.md
105+
git diff --cached --quiet || git commit -m "docs: regenerate README"
106+
git push
107+
```
108+
109+
## Why This Matters
110+
111+
When your code example is included from a real file, the compiler validates it. When your CLI output is captured from the actual binary, it reflects the current behavior. When a build step generates your README, you can't forget to update it.
112+
113+
The result is documentation that is always correct because it's derived from the source of truth — your code.
114+
115+
## Going Further
116+
117+
This same pattern scales beyond READMEs:
118+
119+
- **Website docs**: Use the same source files to generate pages for your docs site (this is exactly how [hypemd.dev](https://hypemd.dev) works — docs are synced from the Hype repo automatically)
120+
- **Blog posts**: Write tutorials with executable code examples that are validated every time you build
121+
- **Training materials**: Include code snippets and exercise outputs that stay current as your codebase evolves
122+
123+
The key insight is simple: documentation should be a build artifact, not a source file. Write it once, generate it everywhere, and let the build system keep it honest.
124+
125+
## Get Started
126+
127+
Install Hype and try it on your own project:
128+
129+
```bash
130+
brew install gopherguides/tap/hype
131+
```
132+
133+
Or with Go:
134+
135+
```bash
136+
go install github.com/gopherguides/hype/cmd/hype@latest
137+
```
138+
139+
Create a `hype.md`, include some source files, and run `hype export -format markdown`. You'll never hand-maintain a README again.

‎layouts/partials/footer.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<a href="/docs/" class="hover:text-emerald-400 transition-colors">Docs</a>
66
<a href="/" class="hover:text-emerald-400 transition-colors">Blog</a>
77
<a href="https://github.com/gopherguides/hype" class="hover:text-emerald-400 transition-colors">GitHub</a>
8+
<a href="https://x.com/hype_markdown" class="hover:text-emerald-400 transition-colors">𝕏</a>
89
<a href="/rss.xml" class="hover:text-emerald-400 transition-colors">RSS</a>
910
</div>
1011
<p>

‎layouts/partials/header.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
<a href="/docs/" class="text-gray-400 hover:text-emerald-400 transition-colors">docs</a>
1010
<a href="/" class="text-gray-400 hover:text-emerald-400 transition-colors">blog</a>
1111
<a href="https://github.com/gopherguides/hype" class="text-gray-400 hover:text-emerald-400 transition-colors">github</a>
12+
<a href="https://x.com/hype_markdown" class="text-gray-400 hover:text-emerald-400 transition-colors">𝕏</a>
1213
<a href="/rss.xml" class="text-gray-400 hover:text-emerald-400 transition-colors">[rss]</a>
1314
</div>
1415
</nav>

0 commit comments

Comments
 (0)