Fetch readme and generate Markdown for CLI flags at build time (#113)

* use custom integration

* add message

* rm cli.md

* trying single code block highlight again. why is it blue???

* steal starlight's colours to make it grey ;-;

* Revert "steal starlight's colours to make it grey ;-;"

This reverts commit 2b85c81.

* Revert "trying single code block highlight again. why is it blue???"

This reverts commit 35353c7.

* biome

* remove escapeMarkdown

* remove default value formatting

* try add remark-smartypants to package.json

* Revert "remove default value formatting"

This reverts commit 0936b31.

* format markdown as rich text, rather than code. i think,

that this is generally nicer to read. However, this means that the
website text is rendered from the same text as the CLI --help. The
website understands Markdown, but the CLI does not (obviously) so we
have to be careful.

I would suggest that when writing help, the focus should be on
readability within the *console*. This means that while Markdown can be
used, it should be limited to syntax which is unobtrusive in raw text.
Raw text is still the main format which the help text will be  rendered
in.

Personally, these would be okay:
- single `*` or `_` for emphasis (with preference for `*`)
- single backticks for inline code
- four space indentation for code blocks
- bullet and numbered lists

Imo, these would *not* be okay, because they appear too jarring
in plain text:
- code blocks with triple backtick fences. this includes any
  astro-specific asides and the like.
- link syntax with `[link](https://url)`
- bold when used for subheadings like `**Note**:`

I think this is a good compromise which lets the same text be usable for
both CLI --help and the website's rich text HTML.

* pnpm lock

* reorder sidebar based on (subjective) frequency of use. also

tweak page titles to be in Title Case.

* extract lychee-version.ts and add note of current version to docs

* Apply suggestions from code review

Co-authored-by: Matthias Endler <[email protected]>

* undo 3 blank lines

---------

Co-authored-by: Matthias Endler <[email protected]>

Author: katrinafyi

astro.config.mjs

@@ -1,10 +1,20 @@
 import starlight from "@astrojs/starlight";
 import { defineConfig } from "astro/config";
+import smartypants from "remark-smartypants";
+import { generateCliOptionsIntegration } from "./src/generate-cli-options";
 
 // https://astro.build/config
 export default defineConfig({
 	site: "https://lychee.cli.rs",
+	markdown: {
+		remarkPlugins: [
+			// automatically converting smart dashes causes problems with cli arguments.
+			// to insert dashes, use unicode or — or –.
+			[smartypants, { dashes: false }],
+		],
+	},
 	integrations: [
+		generateCliOptionsIntegration("src/content/docs/guides/_cli.md"),
 		starlight({
 			expressiveCode: {
 				themes: ["catppuccin-frappe", "catppuccin-latte"],
@@ -38,11 +48,11 @@ export default defineConfig({
 					label: "Guides",
 					items: [
 						"guides/getting-started",
-						"guides/library",
-						"guides/config",
 						"guides/cli",
+						"guides/config",
 						"guides/output",
 						"guides/preprocessing",
+						"guides/library",
 					],
 				},
 				{

package.json

@@ -20,6 +20,7 @@
 		"@astrojs/check": "^0.9.5",
 		"@astrojs/starlight": "^0.36.2",
 		"astro": "^5.15.3",
+		"remark-smartypants": "^3.0.2",
 		"sharp": "^0.34.4",
 		"typescript": "^5.9.3"
 	},

pnpm-lock.yaml

@@ -0,0 +1 @@
+/cli.md

src/content/docs/guides/.gitignore

@@ -0,0 +1,30 @@
+---
+title: Command-Line Flags
+---
+<!--
+The _cli.md file is used as a template to generate the cli.md file
+at build time.
+-->
+
+README-OPTIONS-PLACEHOLDER
+
+## Repeating Options
+
+Some options can be specified multiple times. This is true for:
+
+- `--exclude`
+- `--exclude-path`
+- `--header`
+- `--include`
+- `--remap`
+- `--scheme`
+
+Here is an example:
+
+```bash
+lychee --exclude https://example.com --exclude https://example.org README.md
+```
+
+To specify multiple values in this way, the argument flag should be repeated.
+Otherwise, the extra values would be treated as link checking inputs.
+