Skip to content

Commit 5f5d3b9

Browse files
kryptoniansonkryptonianson
committed
docs: document HTML Escape hints, rules and asCode; refresh app pages
1 parent a9eff30 commit 5f5d3b9

30 files changed

Lines changed: 480 additions & 87 deletions

‎README.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,17 @@ It documents BinaryNoir's open-source VitePress plugins, Vite plugins and comman
66

77
## Plugins demonstrated
88

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-
| [`@binarynoir/vitepress-downloads`](https://github.com/binarynoir/vitepress-downloads) | Downloadable files from a `downloads` folder |
16-
| [`markdown-it-glossary`](https://github.com/binarynoir/markdown-it-glossary) | Hover definitions from `docs/reference/glossary.md` |
17-
| [`@binarynoir/vitepress-html-escape`](https://github.com/binarynoir/vitepress-html-escape) | Stray tags like `Array<string>` and `{{ }}` render as text |
18-
| [`@binarynoir/vite-plugin-optimize-images`](https://github.com/binarynoir/vite-plugin-optimize-images) | Re-compresses images in the build output |
19-
| [`@binarynoir/vite-plugin-image-fallback`](https://github.com/binarynoir/vite-plugin-image-fallback) | Placeholder for missing images (one is missing on purpose) |
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+
| [`@binarynoir/vitepress-downloads`](https://github.com/binarynoir/vitepress-downloads) | Downloadable files from a `downloads` folder |
16+
| [`markdown-it-glossary`](https://github.com/binarynoir/markdown-it-glossary) | Hover definitions from `docs/reference/glossary.md` |
17+
| [`@binarynoir/vitepress-html-escape`](https://github.com/binarynoir/vitepress-html-escape) | Stray tags like `Array<string>` and `{{ }}` render as text; hints underline them in `docs:dev` |
18+
| [`@binarynoir/vite-plugin-optimize-images`](https://github.com/binarynoir/vite-plugin-optimize-images) | Re-compresses images in the build output |
19+
| [`@binarynoir/vite-plugin-image-fallback`](https://github.com/binarynoir/vite-plugin-image-fallback) | Placeholder for missing images (one is missing on purpose) |
2020

2121
## Develop
2222

‎docs/.vitepress/config.mts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,8 @@ export default defineConfig({
111111
md.use(downloadsMarkdown, downloadsOptions);
112112
// @binarynoir/vitepress-html-escape: stray tags like Array<string>, and {{ }} in prose,
113113
// render as text instead of breaking the Vue compile. It runs after every other rule.
114-
md.use(markdownHtmlEscape);
114+
// In `vitepress dev`, hints underline each fix and explain it; `vitepress build` leaves them out.
115+
md.use(markdownHtmlEscape, { hints: process.env.NODE_ENV !== 'production' });
115116
},
116117
},
117118

‎docs/.vitepress/theme/index.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import type { Theme } from 'vitepress';
33
import { registerMarkdownTags } from '@binarynoir/vitepress-markdown-tags/theme';
44
import '@binarynoir/vitepress-markdown-tags/style.css';
55
import { enableGlossaryTooltips } from 'markdown-it-glossary/client';
6+
import { enableHtmlEscapeHints } from '@binarynoir/vitepress-html-escape/client';
67
import './custom.css';
78

89
export default {
@@ -12,5 +13,7 @@ export default {
1213
registerMarkdownTags(app);
1314
// Glossary definitions in a popover on hover, click and tap (title tooltips never show on touch screens).
1415
enableGlossaryTooltips();
16+
// Wavy underlines and fix-it popovers on pages that turn on HTML Escape hints.
17+
enableHtmlEscapeHints();
1518
},
1619
} satisfies Theme;

‎docs/apps/callrx.md‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,32 +6,56 @@ title: callrx
66

77
[[readingTime]]
88

9-
Beautiful amateur radio callsign lookup for the terminal. It looks up US callsigns from the FCC Universal Licensing System and prints them with color, clickable links and a clean table layout.
9+
callrx looks up US amateur radio callsigns from your terminal. It pulls the license record from the FCC Universal Licensing System and prints it with color, clickable links and a clean table layout.
1010

1111
## Install
1212

13+
On macOS or Linux with Homebrew:
14+
1315
```sh
1416
brew install binarynoir/callrx/callrx
1517
```
1618

17-
The Homebrew formula installs a prebuilt release binary for your platform, so no Rust toolchain is needed. You can also download a binary for macOS (Apple Silicon or Intel), Linux (x86_64 or ARM64) or Windows from the [Releases page](https://github.com/binarynoir/callrx/releases), or build from source with `cargo build --release`.
19+
The Homebrew formula installs a prebuilt binary for your platform, so you don't need Rust. You can also download a binary for macOS (Apple Silicon or Intel), Linux (x86_64 or ARM64) or Windows from the [Releases page](https://github.com/binarynoir/callrx/releases), or build from source with `cargo build --release`.
20+
21+
## Sign in
22+
23+
Every lookup needs a personal API key. The easiest way to get one is from callrx itself:
24+
25+
```sh
26+
callrx auth login
27+
```
28+
29+
This opens your browser to confirm a short code, then saves the key on your computer. Check it any time with `callrx auth status`, or remove it with `callrx auth logout`. For scripts and CI, set the `CALLRX_API_KEY` environment variable instead.
30+
31+
## First lookup
32+
33+
```sh
34+
callrx W1AW
35+
```
36+
37+
Results are cached on your computer for 7 days, so looking up the same callsign again is instant.
1838

1939
## Use
2040

2141
```txt
2242
callrx [CALLSIGN]
2343
callrx lookup <CALLSIGN> [OPTIONS]
2444
callrx history <CALLSIGN> [--raw]
45+
callrx auth <login|status|logout>
2546
callrx completions <SHELL>
2647
2748
OPTIONS:
2849
--json Output the raw JSON response
2950
--raw Plain text output (no color, no formatting)
3051
--no-links Disable clickable hyperlinks
52+
--no-cache Skip the local cache and fetch fresh data
53+
--weather Show current weather at the licensee's mailing address
54+
--neighbors Show other active licensees near the same mailing address
3155
```
3256

33-
Links are clickable in terminals that support OSC 8 hyperlinks, such as iTerm2, WezTerm, Windows Terminal and Kitty. Shell completions are available through `callrx completions`.
57+
Links are clickable in terminals that support OSC 8 hyperlinks, such as iTerm2, WezTerm, Windows Terminal and Kitty. `callrx completions` generates tab completion for bash, zsh, fish, elvish and PowerShell.
3458

35-
The [README](https://github.com/binarynoir/callrx#readme) covers the local cache, lookup history, authentication and the supported terminals in detail.
59+
The [README](https://github.com/binarynoir/callrx#readme) covers the local cache, lookup history, installing completions and the data source in detail.
3660

3761
[callrx on GitHub](https://github.com/binarynoir/callrx) · [Homebrew tap](https://github.com/binarynoir/homebrew-callrx)

‎docs/apps/index.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,20 @@ title: Apps
66

77
[[readingTime]]
88

9-
Small command-line tools for people who would rather be told when something changes than keep checking. Everything here installs with a single Homebrew command, and each tool is a single self-contained program.
9+
Small command-line tools for people who would rather be told when something changes than keep checking. Each one is a single self-contained program that installs with one Homebrew command.
1010

1111
| App | What it does | Written in |
1212
| ---------------------------- | ---------------------------------------------------- | ------------------- |
1313
| [NoirWatch](/apps/noirwatch) | Watches web pages and notifies you when they change. | ((tag/Shell/grey)) |
14-
| [NoirCon](/apps/noircon) | Checks that sites and IP addresses are reachable. | ((tag/Shell/grey)) |
14+
| [NoirCon](/apps/noircon) | Tells you when a site, server or port goes down. | ((tag/Shell/grey)) |
1515
| [callrx](/apps/callrx) | Amateur radio callsign lookup in your terminal. | ((tag/Rust/orange)) |
1616

1717
## For users
1818

19-
You do not need to be a developer. If you can paste a command into a terminal, you can install any of these. Start with the page for the app you want. Each one explains what it is for, how to install it, and the first command to run.
19+
You don't need to be a developer. If you can paste a command into a terminal, you can install any of these. Start with the page for the app you want. Each one explains what it is for, how to install it, and the first commands to run. Homebrew installs work on macOS; the pages also cover other ways to install.
2020

2121
## For developers
2222

23-
Each app is open source and welcomes issues and pull requests on its repository. The [roadmap](/apps/roadmap) pulls the status tags from each app's page into one list, so you can see what is done and what is planned.
23+
Each app is open source and welcomes issues and pull requests on its repository. The [roadmap](/apps/roadmap) collects the `Done` and `Planned` status tags from the app pages into one list, so you can see what is finished and what is coming.
2424

2525
Support the work: [Buy Me a Coffee](https://buymeacoffee.com/binarynoir) · [Ko-fi](https://ko-fi.com/binarynoir)

‎docs/apps/noircon.md‎

Lines changed: 39 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,24 @@ title: NoirCon
66

77
[[readingTime]]
88

9-
NoirCon checks whether websites and IP addresses are reachable, and notifies you when one stops responding and when it comes back. It supports Pushover and native desktop notifications.
9+
NoirCon checks whether websites, servers and network services are reachable, and notifies you when one stops responding and again when it comes back. Notifications can go to your desktop (macOS, Linux and Windows) or to your phone through Pushover.
10+
11+
## What it can check
12+
13+
| Check | What it tests |
14+
| -------- | ------------------------------------------------ |
15+
| `HTTP` | A website or URL responds. |
16+
| `PING` | A host or IP address answers a ping. |
17+
| `TCP` | A port accepts connections, such as 443 or 22. |
18+
| `UDP` | A UDP service answers, such as NTP on port 123. |
19+
| `DOMAIN` | A domain registration is not about to expire. |
20+
| `CERT` | A site's TLS certificate is not about to expire. |
1021

1122
## Features
1223

13-
- Monitor addresses to see if they are available
14-
- Pushover and native desktop notifications (macOS, Linux, Windows)
15-
- Configurable check intervals
16-
- Multiple addresses at once
17-
- Custom scripts on `FAIL`, `PASS`, `RECOVERED` and `UNKNOWN`
24+
- Monitor many addresses at once, with configurable check intervals
25+
- Pushover and native desktop notifications
26+
- Run a custom script when a check reports `FAIL`, `PASS`, `RECOVERED` or `UNKNOWN`
1827
- Detailed error reporting and verbose logging
1928
- Background execution
2029

@@ -23,18 +32,38 @@ NoirCon checks whether websites and IP addresses are reachable, and notifies you
2332
On macOS with Homebrew:
2433

2534
```sh
26-
brew tap binarynoir/noircon
27-
brew install noircon
35+
brew install binarynoir/noircon/noircon
2836
```
2937

30-
Or clone it and run it directly (Bash 4 or newer and `curl` required):
38+
On Linux, macOS or Windows (in Git Bash), you can instead clone the repository and run the script directly. It needs Bash 4 or newer and `curl`. Desktop notifications also need `notify-send` on Linux or PowerShell on Windows.
3139

3240
```sh
3341
git clone https://github.com/binarynoir/noircon.git
3442
cd noircon
3543
chmod +x noircon
3644
```
3745

38-
Usage, configuration, service setup and Docker instructions are in the [README](https://github.com/binarynoir/noircon#readme).
46+
If you installed from a clone, type `./noircon` instead of `noircon` in the commands below.
47+
48+
## First run
49+
50+
NoirCon reads the list of things to check from its configuration file, so create that first:
51+
52+
```sh
53+
# Create a configuration file (~/.config/noircon.json on macOS and Linux)
54+
noircon --init
55+
56+
# Open it in your editor and add the addresses to check under "connections"
57+
noircon --edit-config
58+
59+
# Run the checks
60+
noircon
61+
62+
# Run in the background, and stop it later
63+
noircon --start
64+
noircon --stop
65+
```
66+
67+
`noircon --help` lists every option. The [README](https://github.com/binarynoir/noircon#readme) has an example entry for each check type, plus instructions for running NoirCon as a service with systemd, launchd or Windows, and with Docker.
3968

4069
[NoirCon on GitHub](https://github.com/binarynoir/noircon) · [Homebrew tap](https://github.com/binarynoir/homebrew-noircon)

‎docs/apps/noirwatch.md‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ title: NoirWatch
66

77
[[readingTime]]
88

9-
NoirWatch monitors websites for changes and sends a notification when one changes. Notifications can go to your desktop (macOS, Linux and Windows) or to your phone through Pushover.
9+
NoirWatch watches web pages and notifies you when one changes. Notifications can go to your desktop (macOS, Linux and Windows) or to your phone through Pushover.
1010

1111
## Features
1212

@@ -22,32 +22,37 @@ NoirWatch monitors websites for changes and sends a notification when one change
2222
On macOS with Homebrew:
2323

2424
```sh
25-
brew tap binarynoir/noirwatch
26-
brew install noirwatch
25+
brew install binarynoir/noirwatch/noirwatch
2726
```
2827

29-
On Linux, macOS or Windows (Git Bash), clone and run it directly. It needs Bash 4 or newer plus `curl`, `sed`, `shasum` and `xmllint`:
28+
On Linux, macOS or Windows (in Git Bash), you can instead clone the repository and run the script directly. It needs Bash 4 or newer plus `curl`, `sed`, `shasum` and `xmllint`. Desktop notifications also need `notify-send` on Linux or PowerShell on Windows.
3029

3130
```sh
3231
git clone https://github.com/binarynoir/noirwatch.git
3332
cd noirwatch
3433
chmod +x noirwatch
3534
```
3635

36+
If you installed from a clone, type `./noirwatch` instead of `noirwatch` in the commands below.
37+
3738
## First run
3839

3940
```sh
41+
# Create a configuration file (~/.config/noirwatch.json on macOS and Linux)
42+
noirwatch --init
43+
4044
# Watch one page
41-
./noirwatch https://example.com
45+
noirwatch https://example.com
4246

43-
# Watch every URL listed in a file
44-
./noirwatch -f urls
47+
# Watch every page listed under "urls" in the configuration file
48+
noirwatch
4549

46-
# Run in the background
47-
./noirwatch -b https://example.com
50+
# Run in the background, and stop it later
51+
noirwatch --start
52+
noirwatch --stop
4853
```
4954

50-
Create a default configuration file with `noirwatch --init`. The full option list, service setup for systemd, launchd and Windows, and Docker instructions are in the [README](https://github.com/binarynoir/noirwatch#readme).
55+
The configuration file holds the check interval, your notification settings (such as Pushover keys) and the list of pages to watch. Open it in your editor with `noirwatch --edit-config`. `noirwatch --help` lists every option and its current default. The [README](https://github.com/binarynoir/noirwatch#readme) covers the configuration file in detail, plus running NoirWatch as a service with systemd, launchd or Windows, and with Docker.
5156

5257
## Status
5358

@@ -56,7 +61,9 @@ Create a default configuration file with `noirwatch --init`. The full option lis
5661
- ((tag|Done)) Desktop notifications on macOS, Linux and Windows
5762
- ((tag|Done)) Run as a background service
5863
- ((tag|Done)) Run a custom script when a change is detected
59-
- ((tag|Planned)) Change averages for all URLs
64+
- ((tag|Done)) Run a set number of checks, then exit
65+
- ((tag|Done)) JSON configuration with per-page options
66+
- ((tag|Planned)) Change averages for all URLs, in notifications and a history report
6067
- ((tag|Planned)) More notification methods: email, Slack, Discord, Teams, Telegram
6168

6269
[NoirWatch on GitHub](https://github.com/binarynoir/noirwatch) · [Homebrew tap](https://github.com/binarynoir/homebrew-noirwatch)

‎docs/guide/how-this-site-works.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,11 @@ This site is plain VitePress 2 plus nine plugins. There is no hand-written navig
1414
docs/
1515
.nav top navbar order
1616
index.md home page
17+
legal.md, privacy.md, terms.md
18+
footer pages, hidden from the navbar by .nav
1719
plugins/ developer docs for each plugin
1820
.sidebar order and titles for this section
21+
downloads/ files the Downloads demo publishes as-is
1922
apps/ user docs for the CLI apps
2023
guide/ this section
2124
reference/ glossary terms and the generated list of every tag
@@ -36,7 +39,7 @@ docs/
3639
| "Reading time" box | [Reading Time Tag](/plugins/reading-time-tag) | `markdown.config` |
3740
| Dotted-underline hovers | [Glossary Tooltips](/plugins/glossary/) | `markdown.config` |
3841
| File download links | [Downloads](/plugins/downloads) | `markdown.config` and `vite.plugins` |
39-
| Stray `<tags>` shown as text | [HTML Escape](/plugins/html-escape/) | `markdown.config` |
42+
| Stray `<tags>` shown as text | [HTML Escape](/plugins/html-escape/) | `markdown.config`, plus the theme |
4043
| Smaller images | [Optimize Images](/plugins/optimize-images) | `vite.plugins` |
4144
| Placeholder for a missing image | [Image Fallback](/plugins/image-fallback) | `vite.plugins` |
4245

@@ -46,14 +49,14 @@ docs/
4649

4750
## The theme
4851

49-
The only theme code is registering the badge component and loading its stylesheet:
52+
The theme registers the badge component and loads its stylesheet, and turns on the two popovers: glossary definitions, and the HTML Escape hints that explain broken markup:
5053

5154
<<< @/.vitepress/theme/index.ts{ts}
5255

5356
## Adding a page
5457

5558
1. Create `docs/<section>/my-page.md` with a `# Heading`.
56-
2. Optionally add a line for it to that section's `.sidebar` to choose its position and title. Without one it is listed alphabetically.
57-
3. Run `npm run docs:dev`. The page is already in the sidebar.
59+
2. Optionally, add a line for it to that section's `.sidebar` file to choose its position and title. Pages without a line are listed alphabetically where the `...` line is, or at the end if there is none.
60+
3. Run `npm run docs:dev`. The page is already in the sidebar. Anything [HTML Escape](/plugins/html-escape/) had to fix, such as an `Array<T>` outside backticks, has a wavy underline there: hover it to see what is wrong and how to fix it. The deployed site leaves the underlines out.
5861

5962
To add a whole new section, create a folder with an `index.md`. It becomes a navbar entry and its own sidebar automatically.

0 commit comments

Comments
 (0)