Skip to content

Commit

Permalink
docs: set trailingSlash: false to fix refresh issues on GitHub pages
Browse files Browse the repository at this point in the history
Signed-off-by: Haoqun Jiang <haoqunjiang@gmail.com>

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.
<https://stackoverflow.com/a/33271505/2302258>

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.
  • Loading branch information
haoqunjiang committed Oct 9, 2024
1 parent 36948dd commit 65b585e
Show file tree
Hide file tree
Showing 5 changed files with 8 additions and 7 deletions.
2 changes: 1 addition & 1 deletion docs/docs/features/argument-parsing/flags.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down
4 changes: 2 additions & 2 deletions docs/docs/features/argument-parsing/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 2 additions & 2 deletions docs/docs/features/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/docusaurus.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/packages/index.mdx
Original file line number Diff line number Diff line change
@@ -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)

0 comments on commit 65b585e

Please sign in to comment.