From 65b585e877dd0f7cc38015794e02dbc8a60100a0 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Wed, 9 Oct 2024 15:24:16 +0800 Subject: [PATCH] docs: set `trailingSlash: false` to fix refresh issues on GitHub pages Signed-off-by: Haoqun Jiang It's said (and as I tested) that if GitHub Pages detects the URL points to a directory on the server, it would add a trailing slash to the URL on refreshing. Per [Docusaurus's default configuration](https://docusaurus.io/docs/api/docusaurus-config#trailingSlash), `docs/getting-started/overview.mdx` would emit `docs/getting-started/overview/index.html`, therefore GitHub Pages would take `docs/getting-started/overview/` as the canonical URL. But the relative links in the document would not be touched by default, so `./alternatives` remains `./alternatives`, which is `docs/getting-started/alternatives` in the original web page, and `docs/getting-started/overview/alternatives` after refreshing. The latter would be a 404 page. To fix this, we have to enforce a `trailingSlash` style. `trailingSlash: true` requires fixing quite a few links across the docs, so I chose `trailingSlash: false` to keep as many links untouched as possible. --- docs/docs/features/argument-parsing/flags.mdx | 2 +- docs/docs/features/argument-parsing/index.mdx | 4 ++-- docs/docs/features/configuration.mdx | 4 ++-- docs/docusaurus.config.ts | 1 + docs/packages/index.mdx | 4 ++-- 5 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/docs/features/argument-parsing/flags.mdx b/docs/docs/features/argument-parsing/flags.mdx index 63cf39f..2083c45 100644 --- a/docs/docs/features/argument-parsing/flags.mdx +++ b/docs/docs/features/argument-parsing/flags.mdx @@ -40,7 +40,7 @@ import ParsedFlagCode from "./examples/parsed-flag.txt"; Stricli encounters all arguments as strings, and if there is an explicit set of valid string values then the `enum` flag type could be useful. -Given a TypeScript union of string literals (ex: `"a" | "b" | "c"`) the parameter specification can provide a set of all values that should be supported by the flag (ex: `["a", "b", "c"]`). It will then include all values in the help text, and type check a default value if provided. For [auto-complete proposals](../shell-autocomplete), it will automatically suggest any values that match the current partial input. +Given a TypeScript union of string literals (ex: `"a" | "b" | "c"`) the parameter specification can provide a set of all values that should be supported by the flag (ex: `["a", "b", "c"]`). It will then include all values in the help text, and type check a default value if provided. For [auto-complete proposals](../shell-autocomplete.mdx), it will automatically suggest any values that match the current partial input. import EnumFlagCode from "./examples/enum-flag.txt"; diff --git a/docs/docs/features/argument-parsing/index.mdx b/docs/docs/features/argument-parsing/index.mdx index 98a3c68..10a4206 100644 --- a/docs/docs/features/argument-parsing/index.mdx +++ b/docs/docs/features/argument-parsing/index.mdx @@ -4,6 +4,6 @@ sidebar_position: 1 # Argument Parsing -Extending from our core principle of [When Parsing, Form Follows Function](../../getting-started/principles#when-parsing-form-follows-function), Stricli infers the shape of parameter definitions from the TypeScript types used in the implementation. This is achieved with some advanced conditional types that map the types of the parameters to the types of the parser specifications. +Extending from our core principle of [When Parsing, Form Follows Function](../../getting-started/principles.mdx#when-parsing-form-follows-function), Stricli infers the shape of parameter definitions from the TypeScript types used in the implementation. This is achieved with some advanced conditional types that map the types of the parameters to the types of the parser specifications. -Stricli supports both [named flags](./flags) and [positional arguments](./positional) when defining parameters. +Stricli supports both [named flags](./flags.mdx) and [positional arguments](./positional.mdx) when defining parameters. diff --git a/docs/docs/features/configuration.mdx b/docs/docs/features/configuration.mdx index f346a54..1ec1298 100644 --- a/docs/docs/features/configuration.mdx +++ b/docs/docs/features/configuration.mdx @@ -58,7 +58,7 @@ The configuration in `documentation` controls how values and names in the applic ### Always Show `--helpAll` Flag -Stricli provides a built-in `--help` flag that prints out the help text for a command/route. This help text will never include [hidden flags](./argument-parsing/flags#hidden), but those can be visualized with the `--helpAll` built-in flag. It will print all flags/routes, but is not listed as a flag in the normal help text. This built-in is always available, but if you want to make it visible to users at all times you can set `alwaysShowHelpAllFlag` to `true`. +Stricli provides a built-in `--help` flag that prints out the help text for a command/route. This help text will never include [hidden flags](./argument-parsing/flags.mdx#hidden), but those can be visualized with the `--helpAll` built-in flag. It will print all flags/routes, but is not listed as a flag in the normal help text. This built-in is always available, but if you want to make it visible to users at all times you can set `alwaysShowHelpAllFlag` to `true`. ### Use Alias in Usage Line @@ -149,7 +149,7 @@ When a command's implementation function throws an exception, that triggers a fa ## Autocomplete -The [auto-complete feature](./shell-autocomplete)) can be customized with the `completion` configuration. +The [auto-complete feature](./shell-autocomplete.mdx)) can be customized with the `completion` configuration. ### Alias Support diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 97a9c8c..02731c8 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -21,6 +21,7 @@ const config: Config = { onBrokenLinks: "throw", onBrokenMarkdownLinks: "throw", onDuplicateRoutes: "throw", + trailingSlash: false, // Even if you don't use internationalization, you can use this field to set // useful metadata like html lang. For example, if your site is Chinese, you diff --git a/docs/packages/index.mdx b/docs/packages/index.mdx index 6e7eba9..637e91b 100644 --- a/docs/packages/index.mdx +++ b/docs/packages/index.mdx @@ -1,4 +1,4 @@ # Packages -- [`@stricli/core`](./core) -- [`@stricli/auto-complete`](./auto-complete) +- [`@stricli/core`](./core/index.md) +- [`@stricli/auto-complete`](./auto-complete/index.md)