Skip to content

Commit bd2aa16

Browse files
TMHSDigitalclaude
andcommitted
docs(site): rebrand and rebuild the GitHub Pages site
A new identity built from what subenum does: the mark is an apex branching into two resolved names and one NXDOMAIN, and the palette is the outcome taxonomy itself (resolved, nxdomain, timeout, refused), used the same way from the hero to the verdict gauges. - Landing page (index.html) leads with a replayed scan: stdout names, the run.json outcome counts and the verdict with its real reason string. Sections explain the three verdicts, list checkable claims with the flag or report field behind each, and show workflows. - Docs layout: sticky sidebar from _data/nav.yml, generated on-page contents with scrollspy, heading anchors, previous/next links and an edit link. Client-side search over a build-time search.json (/ or Ctrl+K), light and dark themes, a mobile drawer, and a 404. - New pages: Getting started, CLI reference (the flag table moves off the home page) and Go library (samples compile against pkg/subenum). - Outlined SVG wordmark for the README, new favicon and social card. - Developer Guide documents the site structure and a local preview using the same jekyll-build-pages image as the workflow. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 1f5139c commit bd2aa16

21 files changed

Lines changed: 2786 additions & 646 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2323
- Run-quality report: `-stats <file>` writes a schema-versioned JSON summary of a run (outcomes per target, DNS queries actually sent, achieved query rate, wildcard fingerprint, candidates skipped by `-max-queries`) with a `complete` / `degraded` / `unreliable` verdict and its reason. `-format jsonl` ends with the same object as its last line. The README documents the schema and how to gate CI on the verdict (#70).
2424

2525
### Changed
26+
- The website is redesigned and rebranded: a new mark and wordmark (an apex branching into resolved and NXDOMAIN names), a palette built from the outcome colours, a landing page that replays a scan and explains the three verdicts, and a docs layout with a sidebar, on-page contents, previous/next links, client-side search (`/` or Ctrl+K), light and dark themes and a 404 page. New pages: Getting started, CLI reference (the flag table moves off the home page) and Go library. Navigation is driven by `docs/_data/nav.yml`; the Developer Guide explains how to preview the site locally.
2627
- Releases are built by GoReleaser from `.goreleaser.yaml`: static, trimmed binaries for Linux, macOS, Windows and FreeBSD (adding windows/arm64, linux/386 and FreeBSD) packed in `.tar.gz`/`.zip` archives with LICENSE, README and CHANGELOG, plus `checksums.txt`, an SPDX SBOM per archive, a keyless cosign signature over the checksums, build-provenance attestations, and release notes taken from the tag's CHANGELOG section. The release stays a draft until provenance is attested. CI runs the same pipeline in snapshot mode on every push to main. Asset names change from `subenum-linux-amd64` to `subenum_<version>_linux_amd64.tar.gz` (#61).
2728
- The GitHub Pages site is current: the hero shows real output (resolved names only), the flag table is generated from the CLI's own flags (a test fails when it drifts; `make docs-flags` regenerates it), the features cover the run-quality report, resolver pool, takeover hints, monitoring and scope control, there is a GHCR quick start and a Monitoring page, shared links get `og:`/Twitter preview cards with a new social image, the internal `DOCUMENTATION_STRUCTURE.md` template is no longer published, and the unused Cayman theme is gone. The README's "Why subenum" is updated to match (#64).
2829
- Tests run against a shared, scriptable DNS server, `internal/dnstest`, built on `golang.org/x/net/dns/dnsmessage`. It replaces the two hand-encoded responders, answers per name and type with records, any RCODE, NODATA with SOA, delays, drops or truncation, and counts queries per name and type. New tests cover NODATA, a resolver at an IPv6 address, exact wire queries per record type, and TCP fallback after truncation (#67).

‎README.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<div align="center">
22

3-
<img src="docs/assets/wordmark.svg" alt="subenum" width="600"/>
3+
<img src="docs/assets/wordmark.svg" alt="subenum: every DNS query, accounted for" width="520"/>
44

55
<br>
66

@@ -24,7 +24,7 @@
2424

2525
<br>
2626

27-
[Quick Start](#quick-start) &nbsp;|&nbsp; [Configuration](#configuration) &nbsp;|&nbsp; [Usage](#usage) &nbsp;|&nbsp; [Architecture](#system-architecture) &nbsp;|&nbsp; [Changelog](./CHANGELOG.md)
27+
[Website](https://tmhsdigital.github.io/subenum/) &nbsp;|&nbsp; [Quick Start](#quick-start) &nbsp;|&nbsp; [Configuration](#configuration) &nbsp;|&nbsp; [Usage](#usage) &nbsp;|&nbsp; [Architecture](#system-architecture) &nbsp;|&nbsp; [Changelog](./CHANGELOG.md)
2828

2929
</div>
3030

@@ -588,15 +588,15 @@ subenum/
588588
│ └── PULL_REQUEST_TEMPLATE.md
589589
├── data/
590590
│ └── wordlist.txt # Default wordlist for Docker/Make
591-
├── docs/
592-
│ ├── assets/
593-
│ │ └── tui-form.png # TUI screenshot
591+
├── docs/ # Source of the website (GitHub Pages)
592+
│ ├── assets/ # Brand, CSS, JS, TUI screenshot
594593
│ ├── ARCHITECTURE.md
595594
│ ├── CONTRIBUTING.md
596595
│ ├── DEVELOPER_GUIDE.md
597-
│ ├── docker.md
596+
│ ├── start.md, cli.md, library.md, labs.md, monitoring.md, docker.md
597+
│ ├── _data/nav.yml # Site navigation
598598
│ ├── _config.yml
599-
│ └── index.md
599+
│ └── index.html # Landing page
600600
├── examples/
601601
│ ├── sample_wordlist.txt
602602
│ ├── advanced_usage.md

‎docs/404.html‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
layout: base
3+
title: Page not found
4+
body_class: is-404
5+
permalink: /404.html
6+
---
7+
<main id="content" class="notfound">
8+
<div class="notfound-inner">
9+
<pre class="notfound-dig" aria-hidden="true">;; -&gt;&gt;HEADER&lt;&lt;- opcode: QUERY, <span class="nx">status: NXDOMAIN</span>
10+
;; QUESTION SECTION:
11+
;<span data-path>this-page</span>.tmhsdigital.github.io. IN A</pre>
12+
<h1>This page doesn't resolve.</h1>
13+
<p>The address may have moved when the docs were reorganized. Search the docs, or start from one of these.</p>
14+
<div class="hero-actions">
15+
<button type="button" class="btn btn-primary" data-search-open>Search the docs</button>
16+
<a class="btn" href="{{ '/' | relative_url }}">Home</a>
17+
<a class="btn" href="{{ '/start.html' | relative_url }}">Getting started</a>
18+
</div>
19+
</div>
20+
</main>

‎docs/DEVELOPER_GUIDE.md‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -81,9 +81,12 @@ subenum/
8181
│ ├── DOCUMENTATION_STRUCTURE.md
8282
│ ├── ROADMAP.md # Planned work
8383
│ ├── docker.md # Container setup and volume mounting
84+
│ ├── start.md, cli.md, library.md, labs.md, monitoring.md # User guides
8485
│ ├── _config.yml # Jekyll config for GitHub Pages
85-
│ ├── _includes/, _layouts/, assets/ # Jekyll site templates, CSS, images
86-
│ └── index.md # GitHub Pages landing page
86+
│ ├── _data/nav.yml # Site navigation: sidebar, footer, search, reading order
87+
│ ├── _includes/, _layouts/, assets/ # Jekyll site templates, CSS, JS, images
88+
│ ├── search.json # Search index, generated at build time
89+
│ └── index.html # GitHub Pages landing page
8790
├── examples/
8891
│ ├── sample_wordlist.txt # 50-entry starter wordlist
8992
│ ├── sample_domains.txt # Sample domain list for -dL
@@ -286,6 +289,28 @@ If you need to add a further dependency:
286289
```
287290
3. Run `go mod tidy` to update the `go.mod` and `go.sum` files.
288291
292+
## Working on the Website
293+
294+
The site at [tmhsdigital.github.io/subenum](https://tmhsdigital.github.io/subenum/) is built from `docs/` by the stock GitHub Pages Jekyll action (`.github/workflows/pages.yml`), with no theme and no JavaScript dependencies.
295+
296+
- `docs/index.html` is the landing page; every other page is Markdown with `layout: default`, which adds the sidebar, the on-page contents and the previous/next links.
297+
- `docs/_data/nav.yml` is the single list of pages and sections. Add a new page there or it won't appear in the sidebar, the footer or search.
298+
- `docs/search.json` is generated at build time from the pages in `nav.yml`; `docs/assets/js/site.js` runs search, tabs, copy buttons and the hero animation.
299+
- The palette lives at the top of `docs/assets/css/site.css`. The outcome colours (resolved, nxdomain, timeout, refused) mean the same thing everywhere, so reuse the tokens rather than adding colours.
300+
301+
To preview locally, build with the same image the workflow uses and serve the output:
302+
303+
```bash
304+
docker run --rm -w /src -v "$PWD/docs:/src/docs:ro" -v "$PWD/docs/_preview/site:/src/_site" \
305+
-e INPUT_SOURCE=./docs -e INPUT_DESTINATION=./_site -e INPUT_TOKEN="$(gh auth token)" \
306+
-e GITHUB_WORKSPACE=/src -e GITHUB_REPOSITORY=TMHSDigital/subenum -e PAGES_REPO_NWO=TMHSDigital/subenum \
307+
ghcr.io/actions/jekyll-build-pages:v1.0.13
308+
mkdir -p /tmp/subenum-site && rm -rf /tmp/subenum-site/subenum && cp -r docs/_preview/site /tmp/subenum-site/subenum
309+
python3 -m http.server 4000 -d /tmp/subenum-site # http://localhost:4000/subenum/
310+
```
311+
312+
The token is needed because the header shows the latest release tag. `docs/_preview/` is gitignored.
313+
289314
## Already Shipped
290315

291316
The following capabilities are implemented and available today:

‎docs/_config.yml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,16 @@
11
title: subenum
2-
description: Subdomain enumeration you can trust - every DNS query accounted for. A single static Go binary.
2+
tagline: every DNS query, accounted for
3+
description: Subdomain enumeration you can trust. subenum classifies every DNS lookup, grades the run complete, degraded or unreliable, and ships as a single static Go binary.
34
show_downloads: false
45
url: "https://tmhsdigital.github.io"
56
baseurl: "/subenum"
67
repository: TMHSDigital/subenum
78
# Shown when a page link is shared (og:image / twitter:card).
89
social_image: /assets/social-preview.png
10+
kramdown:
11+
input: GFM
12+
hard_wrap: false
13+
auto_ids: true
914
# Internal templates and local build output are not part of the site.
1015
exclude:
1116
- DOCUMENTATION_STRUCTURE.md

‎docs/_data/nav.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Documentation navigation: drives the sidebar, the mobile drawer, the footer
2+
# columns and the previous/next links at the bottom of each page. A page that
3+
# is not listed here still builds, it just has no place in the reading order.
4+
- section: Start here
5+
footer: true
6+
pages:
7+
- title: Getting started
8+
url: /start.html
9+
- title: CLI reference
10+
url: /cli.html
11+
12+
- section: Guides
13+
footer: true
14+
pages:
15+
- title: Monitoring
16+
url: /monitoring.html
17+
- title: Labs
18+
url: /labs.html
19+
- title: Docker
20+
url: /docker.html
21+
- title: Go library
22+
url: /library.html
23+
24+
- section: Internals
25+
pages:
26+
- title: Architecture
27+
url: /ARCHITECTURE.html
28+
- title: Developer guide
29+
url: /DEVELOPER_GUIDE.html
30+
31+
- section: Project
32+
footer: true
33+
pages:
34+
- title: Contributing
35+
url: /CONTRIBUTING.html
36+
- title: Roadmap
37+
url: /ROADMAP.html
38+
- title: Code of conduct
39+
url: /CODE_OF_CONDUCT.html

‎docs/_includes/doc-nav.html‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{%- for group in site.data.nav %}
2+
<div class="nav-group">
3+
<h2 class="nav-group-title">{{ group.section }}</h2>
4+
<ul>
5+
{%- for item in group.pages %}
6+
<li><a href="{{ item.url | relative_url }}"{% if page.url == item.url %} aria-current="page"{% endif %}>{{ item.title }}</a></li>
7+
{%- endfor %}
8+
</ul>
9+
</div>
10+
{%- endfor %}

‎docs/_includes/page-nav.html‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/_layouts/base.html‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
<!DOCTYPE html>
2+
<html lang="en-US" data-theme="dark">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
{%- if page.title == "Home" -%}
7+
{%- assign page_title = site.title | append: ": " | append: site.tagline -%}
8+
{%- else -%}
9+
{%- assign page_title = page.title | append: " | " | append: site.title -%}
10+
{%- endif -%}
11+
{%- assign page_description = page.description | default: site.description %}
12+
<title>{{ page_title }}</title>
13+
<meta name="description" content="{{ page_description }}">
14+
<meta name="color-scheme" content="dark light">
15+
<meta name="theme-color" content="#0E1726">
16+
<link rel="canonical" href="{{ page.url | absolute_url }}">
17+
<meta property="og:type" content="website">
18+
<meta property="og:site_name" content="{{ site.title }}">
19+
<meta property="og:title" content="{{ page_title }}">
20+
<meta property="og:description" content="{{ page_description }}">
21+
<meta property="og:url" content="{{ page.url | absolute_url }}">
22+
<meta property="og:image" content="{{ site.social_image | absolute_url }}">
23+
<meta property="og:image:width" content="1200">
24+
<meta property="og:image:height" content="630">
25+
<meta property="og:image:alt" content="subenum: every DNS query, accounted for">
26+
<meta name="twitter:card" content="summary_large_image">
27+
<meta name="twitter:title" content="{{ page_title }}">
28+
<meta name="twitter:description" content="{{ page_description }}">
29+
<meta name="twitter:image" content="{{ site.social_image | absolute_url }}">
30+
<link rel="icon" href="{{ '/assets/favicon.svg' | relative_url }}" type="image/svg+xml">
31+
<script>
32+
// Set the theme before first paint so a light-mode reader never sees a dark flash.
33+
(function () {
34+
var t = null;
35+
try { t = localStorage.getItem('subenum-theme'); } catch (e) {}
36+
if (t !== 'light' && t !== 'dark') {
37+
t = window.matchMedia && matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
38+
}
39+
document.documentElement.setAttribute('data-theme', t);
40+
})();
41+
</script>
42+
<link rel="preconnect" href="https://fonts.googleapis.com">
43+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
44+
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&family=IBM+Plex+Sans+Condensed:wght@500;600;700&family=IBM+Plex+Sans:ital,wght@0,400;0,500;0,600;1,400&display=swap">
45+
<link rel="stylesheet" href="{{ '/assets/css/site.css' | relative_url }}?v={{ site.time | date: '%s' }}">
46+
</head>
47+
<body class="{{ page.body_class | default: 'is-doc' }}">
48+
<a class="skip-link" href="#content">Skip to content</a>
49+
50+
<header class="topbar">
51+
<div class="topbar-inner">
52+
<a class="brand" href="{{ '/' | relative_url }}" aria-label="subenum home">
53+
<svg class="brand-mark" viewBox="2 2 26 28" aria-hidden="true">
54+
<path d="M10 16H14M14 8V24M14 8H19M14 16H19M14 24H19" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
55+
<circle cx="7.5" cy="16" r="3.5" class="mark-apex"/>
56+
<rect x="19.5" y="5" width="6" height="6" rx="1.2" class="mark-hit"/>
57+
<rect x="19.5" y="13" width="6" height="6" rx="1.2" class="mark-hit"/>
58+
<rect x="20.25" y="21.75" width="4.5" height="4.5" rx="0.9" class="mark-miss"/>
59+
</svg>
60+
<span class="brand-word">subenum</span>
61+
</a>
62+
{%- if site.github.latest_release.tag_name %}
63+
<a class="release-tag" href="{{ site.github.latest_release.html_url }}" title="Latest release">{{ site.github.latest_release.tag_name }}</a>
64+
{%- endif %}
65+
66+
<nav class="topnav" aria-label="Primary">
67+
<a href="{{ '/start.html' | relative_url }}"{% if page.url == '/start.html' %} aria-current="page"{% endif %}>Docs</a>
68+
<a href="{{ '/cli.html' | relative_url }}"{% if page.url == '/cli.html' %} aria-current="page"{% endif %}>CLI reference</a>
69+
<a href="{{ '/labs.html' | relative_url }}"{% if page.url == '/labs.html' %} aria-current="page"{% endif %}>Labs</a>
70+
<a href="{{ '/library.html' | relative_url }}"{% if page.url == '/library.html' %} aria-current="page"{% endif %}>Go library</a>
71+
</nav>
72+
73+
<div class="topbar-tools">
74+
<button type="button" class="search-trigger" data-search-open aria-label="Search the docs">
75+
<svg viewBox="0 0 20 20" aria-hidden="true"><circle cx="8.5" cy="8.5" r="5.5"/><path d="M13 13l4 4"/></svg>
76+
<span class="search-trigger-label">Search</span>
77+
<kbd>/</kbd>
78+
</button>
79+
<button type="button" class="icon-btn" data-theme-toggle aria-label="Switch to light theme">
80+
<svg class="i-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.5"/><path d="M10 2v2M10 16v2M2 10h2M16 10h2M4.3 4.3l1.4 1.4M14.3 14.3l1.4 1.4M4.3 15.7l1.4-1.4M14.3 5.7l1.4-1.4"/></svg>
81+
<svg class="i-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M16 12.5A6.5 6.5 0 0 1 7.5 4a6.5 6.5 0 1 0 8.5 8.5z"/></svg>
82+
</button>
83+
<a class="icon-btn" href="https://github.com/{{ site.repository }}" aria-label="subenum on GitHub">
84+
<svg viewBox="0 0 16 16" aria-hidden="true" class="i-fill"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>
85+
</a>
86+
<button type="button" class="icon-btn menu-btn" data-menu-open aria-label="Open navigation" aria-expanded="false" aria-controls="drawer">
87+
<svg viewBox="0 0 20 20" aria-hidden="true"><path d="M3 6h14M3 10h14M3 14h14"/></svg>
88+
</button>
89+
</div>
90+
</div>
91+
</header>
92+
93+
<div class="drawer" id="drawer" hidden>
94+
<div class="drawer-scrim" data-menu-close></div>
95+
<nav class="drawer-panel" aria-label="Documentation">
96+
<div class="drawer-head">
97+
<span class="brand-word">subenum</span>
98+
<button type="button" class="icon-btn" data-menu-close aria-label="Close navigation">
99+
<svg viewBox="0 0 20 20" aria-hidden="true"><path d="M5 5l10 10M15 5L5 15"/></svg>
100+
</button>
101+
</div>
102+
<a class="drawer-home" href="{{ '/' | relative_url }}">Home</a>
103+
{% include doc-nav.html %}
104+
</nav>
105+
</div>
106+
107+
{{ content }}
108+
109+
<footer class="site-footer">
110+
<div class="footer-inner">
111+
<div class="footer-brand">
112+
<span class="brand-word">subenum</span>
113+
<p>Subdomain enumeration that tells you how far to trust the answer. Free software under GPL-3.0, maintained by <a href="https://github.com/TMHSDigital">TMHSDigital</a>.</p>
114+
<p class="footer-legal">Scan only domains you own or have written permission to test.</p>
115+
</div>
116+
{%- for group in site.data.nav %}
117+
{%- if group.footer %}
118+
<div class="footer-col">
119+
<h2>{{ group.section }}</h2>
120+
<ul>
121+
{%- for item in group.pages %}
122+
<li><a href="{% if item.external %}{{ item.url }}{% else %}{{ item.url | relative_url }}{% endif %}">{{ item.title }}</a></li>
123+
{%- endfor %}
124+
</ul>
125+
</div>
126+
{%- endif %}
127+
{%- endfor %}
128+
<div class="footer-col">
129+
<h2>Elsewhere</h2>
130+
<ul>
131+
<li><a href="https://github.com/{{ site.repository }}/releases">Releases</a></li>
132+
<li><a href="https://github.com/{{ site.repository }}/blob/main/CHANGELOG.md">Changelog</a></li>
133+
<li><a href="https://github.com/{{ site.repository }}/blob/main/SECURITY.md">Security policy</a></li>
134+
<li><a href="https://pkg.go.dev/github.com/{{ site.repository }}/pkg/subenum">pkg.go.dev</a></li>
135+
</ul>
136+
</div>
137+
</div>
138+
</footer>
139+
140+
<div class="search" data-search hidden>
141+
<div class="search-scrim" data-search-close></div>
142+
<div class="search-panel" role="dialog" aria-modal="true" aria-label="Search the docs">
143+
<div class="search-field">
144+
<svg viewBox="0 0 20 20" aria-hidden="true"><circle cx="8.5" cy="8.5" r="5.5"/><path d="M13 13l4 4"/></svg>
145+
<input type="search" placeholder="Search flags, guides, internals" autocomplete="off" spellcheck="false" aria-label="Search query" aria-controls="search-results" data-search-input>
146+
<kbd>esc</kbd>
147+
</div>
148+
<ol class="search-results" id="search-results" data-search-results></ol>
149+
<p class="search-empty" data-search-empty hidden></p>
150+
</div>
151+
</div>
152+
153+
<script>window.SUBENUM = { searchIndex: "{{ '/search.json' | relative_url }}" };</script>
154+
<script src="{{ '/assets/js/site.js' | relative_url }}?v={{ site.time | date: '%s' }}" defer></script>
155+
</body>
156+
</html>

0 commit comments

Comments
 (0)