Skip to content

Commit a16fd7e

Browse files
kryptoniansonkryptonianson
committed
feat: BinaryNoir developer hub and live plugin demo site
VitePress 2 site documenting the @binarynoir plugins and apps, built with all seven plugins, and published to GitHub Pages by GitHub Actions.
0 parents  commit a16fd7e

39 files changed

Lines changed: 4417 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: CI
2+
3+
# Build-only check for pull requests. Deploys happen from deploy.yml on main.
4+
on:
5+
pull_request:
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
build:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v7
15+
with:
16+
fetch-depth: 0
17+
- uses: actions/setup-node@v7
18+
with:
19+
node-version: 24
20+
cache: npm
21+
- run: npm ci
22+
- run: npm run format:check
23+
- run: npm run docs:build

‎.github/workflows/deploy.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Deploy site to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
# Pages deploys need these three, nothing else.
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
# One deploy at a time. Let a running deploy finish rather than cancel it
15+
# halfway, but drop queued runs in favor of the newest commit.
16+
concurrency:
17+
group: pages
18+
cancel-in-progress: false
19+
20+
jobs:
21+
build:
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@v7
25+
with:
26+
# Full history so VitePress `lastUpdated` timestamps are correct.
27+
fetch-depth: 0
28+
- uses: actions/setup-node@v7
29+
with:
30+
node-version: 24
31+
cache: npm
32+
- uses: actions/configure-pages@v6
33+
- run: npm ci
34+
- run: npm run format:check
35+
- run: npm run docs:build
36+
- uses: actions/upload-pages-artifact@v5
37+
with:
38+
path: docs/.vitepress/dist
39+
40+
deploy:
41+
needs: build
42+
runs-on: ubuntu-latest
43+
environment:
44+
name: github-pages
45+
url: ${{ steps.deployment.outputs.page_url }}
46+
steps:
47+
- id: deployment
48+
uses: actions/deploy-pages@v5

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
node_modules/
2+
docs/.vitepress/dist/
3+
docs/.vitepress/cache/
4+
.DS_Store
5+
*.log

‎.nvmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
24

‎.prettierignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules
2+
docs/.vitepress/dist
3+
docs/.vitepress/cache
4+
package-lock.json

‎.prettierrc.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"singleQuote": true,
3+
"printWidth": 100,
4+
"proseWrap": "preserve"
5+
}

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 John Smith III
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# binarynoir.github.io
2+
3+
The [BinaryNoir](https://github.com/binarynoir) developer hub, live at **https://binarynoir.github.io**.
4+
5+
It documents BinaryNoir's open-source VitePress plugins, Vite plugins and command-line apps, and it is built with every one of those plugins, so it doubles as a working demo of how they fit together.
6+
7+
## Plugins demonstrated
8+
9+
| Package | Role on this site |
10+
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
11+
| [`@binarynoir/vitepress-auto-sidebar`](https://github.com/binarynoir/vitepress-auto-sidebar) | Builds the sidebar from the folder tree |
12+
| [`@binarynoir/vitepress-auto-navbar`](https://github.com/binarynoir/vitepress-auto-navbar) | Builds the top navbar from the folder tree |
13+
| [`@binarynoir/vitepress-markdown-tags`](https://github.com/binarynoir/vitepress-markdown-tags) | Status badges and tagged-page lists |
14+
| [`@binarynoir/vitepress-reading-time-tag`](https://github.com/binarynoir/vitepress-reading-time-tag) | `[[readingTime]]` tip blocks |
15+
| [`markdown-it-glossary`](https://github.com/binarynoir/markdown-it-glossary) | Hover definitions from `docs/glossary.md` |
16+
| [`@binarynoir/vite-plugin-optimize-images`](https://github.com/binarynoir/vite-plugin-optimize-images) | Re-compresses images in the build output |
17+
| [`@binarynoir/vite-plugin-image-fallback`](https://github.com/binarynoir/vite-plugin-image-fallback) | Placeholder for missing images (one is missing on purpose) |
18+
19+
## Develop
20+
21+
Requires Node 22 or newer.
22+
23+
```sh
24+
npm install
25+
npm run docs:dev # dev server
26+
npm run docs:build # production build into docs/.vitepress/dist
27+
npm run docs:preview # serve the production build
28+
npm run format:check # prettier, also run in CI
29+
```
30+
31+
## Deploy
32+
33+
Pushing to `main` runs [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml), which builds the site and publishes it with GitHub Pages. Pull requests run [`ci.yml`](.github/workflows/ci.yml), which builds without deploying. See [docs/guide/deploying.md](docs/guide/deploying.md) for the full setup.
34+
35+
The repository's Pages source must be set to **GitHub Actions** (Settings → Pages).
36+
37+
## A note on the missing image
38+
39+
`docs/plugins/image-fallback.md` references an image that does not exist, on purpose, to demonstrate the image-fallback plugin. The build logs a warning for it. That is expected.
40+
41+
## License
42+
43+
[MIT](LICENSE)

‎docs/.nav‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Top navbar order. Everything not listed falls in at "..." alphabetically.
2+
plugins
3+
apps
4+
guide
5+
...
6+
glossary.md
7+
tagged-pages.md

‎docs/.vitepress/config.mts‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
import { defineConfig } from 'vitepress';
2+
import path from 'node:path';
3+
import { glossaryAbbr } from 'markdown-it-glossary';
4+
import { readingTimeTag } from '@binarynoir/vitepress-reading-time-tag';
5+
import { markdownTags, stripTags } from '@binarynoir/vitepress-markdown-tags';
6+
import { taggedPagesVitePlugin } from '@binarynoir/vitepress-markdown-tags/vitepress';
7+
import { generateNav } from '@binarynoir/vitepress-auto-navbar';
8+
import { generateSidebar } from '@binarynoir/vitepress-auto-sidebar';
9+
import { imageFallbackPlugin } from '@binarynoir/vite-plugin-image-fallback';
10+
import { optimizeImagesPlugin } from '@binarynoir/vite-plugin-optimize-images';
11+
12+
// import.meta.dirname, not __dirname: VitePress configs are ESM.
13+
const docsRoot = path.resolve(import.meta.dirname, '..');
14+
15+
const SITE_URL = 'https://binarynoir.github.io';
16+
17+
export default defineConfig({
18+
title: 'BinaryNoir',
19+
description: 'Open-source tools and VitePress plugins by BinaryNoir, with live demos.',
20+
lang: 'en-US',
21+
cleanUrls: true,
22+
lastUpdated: true,
23+
24+
sitemap: { hostname: SITE_URL },
25+
26+
head: [
27+
['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
28+
['meta', { name: 'theme-color', content: '#7a5add' }],
29+
['meta', { property: 'og:type', content: 'website' }],
30+
['meta', { property: 'og:title', content: 'BinaryNoir' }],
31+
[
32+
'meta',
33+
{
34+
property: 'og:description',
35+
content: 'Open-source tools and VitePress plugins by BinaryNoir, with live demos.',
36+
},
37+
],
38+
['meta', { property: 'og:url', content: SITE_URL }],
39+
],
40+
41+
themeConfig: {
42+
logo: '/logo.svg',
43+
44+
// @binarynoir/vitepress-auto-navbar: top nav built from the folder tree.
45+
// `.nav` files set order and titles; `.inherit` borrows titles from `.sidebar`.
46+
nav: generateNav(docsRoot, {
47+
maxDepth: 2,
48+
configFilenames: ['.nav', '.sidebar'],
49+
}),
50+
51+
// @binarynoir/vitepress-auto-sidebar: one sidebar per top-level folder.
52+
sidebar: generateSidebar(docsRoot, {
53+
maxDepth: 3,
54+
maxTitleLength: 50,
55+
}),
56+
57+
socialLinks: [{ icon: 'github', link: 'https://github.com/binarynoir' }],
58+
59+
search: { provider: 'local' },
60+
61+
editLink: {
62+
pattern: 'https://github.com/binarynoir/binarynoir.github.io/edit/main/docs/:path',
63+
text: 'Suggest a change to this page',
64+
},
65+
66+
footer: {
67+
message: 'Released under the MIT License. Built with VitePress and the plugins it documents.',
68+
copyright: 'Copyright © John Smith III / BinaryNoir',
69+
},
70+
},
71+
72+
markdown: {
73+
theme: { light: 'github-light', dark: 'github-dark' },
74+
config(md) {
75+
// markdown-it-glossary: hover definitions from docs/glossary.md on every page.
76+
// A page opts out with `glossary: false` in its frontmatter.
77+
md.use(glossaryAbbr, { file: path.join(docsRoot, 'glossary.md') });
78+
// @binarynoir/vitepress-reading-time-tag: [[readingTime]] becomes a tip block.
79+
md.use(readingTimeTag);
80+
// @binarynoir/vitepress-markdown-tags: ((tag|Done|green)) becomes a badge.
81+
md.use(markdownTags);
82+
},
83+
},
84+
85+
// Keep ((tag|...)) syntax out of <title>, search results and the page outline.
86+
transformPageData(pageData) {
87+
if (typeof pageData.title === 'string') {
88+
pageData.title = stripTags(pageData.title);
89+
}
90+
if (typeof pageData.frontmatter?.title === 'string') {
91+
pageData.frontmatter.title = stripTags(pageData.frontmatter.title);
92+
}
93+
},
94+
95+
vite: {
96+
plugins: [
97+
// Missing image imports become a placeholder plus a console warning
98+
// instead of failing the build.
99+
imageFallbackPlugin(),
100+
// Re-compress PNG/JPEG/WebP in the build output. Source files are untouched.
101+
optimizeImagesPlugin({ verbose: true }),
102+
// Keeps `tagged: true` pages current while running `vitepress dev`.
103+
taggedPagesVitePlugin(),
104+
],
105+
},
106+
});

0 commit comments

Comments
 (0)