CLI usage document Naming convention is nearly non-existent and there is a bunch of missing options such as default document path and ignoring dotfiles, but at least this is better than nothing.

Changes

4 changed files (+154/-3)

• docs/en/References/Config.md (new)
  • @@ -0,0 +1,134 @@
    + ## Input options + + ### `input.path` + + - Type: `string` (file path) + - CLI: First positional argument + - Required + + Path to a Vault (source directory includes documents). + Path needs to be relative and resolved from the config file. + + ## Output options + + ### `output.path` + + - Type: `string` (file path) + - CLI: `--out <PATH>` option + - Required + + Path to the output directory. + Path needs to be relative and resolved from the config file. + + ### `output.precompress` + + - Type: `boolean` + - CLI: `--precompress` flag + + Whether to compress `.html`, `.css` and `.js` files into `.<ext>.gz`, `.<ext>.br` and `.<ext>.zst` files. + For example, if an output directory contains `index.html`, Macana also generates + - `index.html.gz` (Gzip) + - `index.html.br` (Brotli) + - `index.html.zst` (ZStandard) + + inside the same directory. + + ## Website metadata options + + ### `metadata.name` + + - Type: `string` + - CLI: `--name <TEXT>` option + - Required + + Website name, title. + `<title>` and a title section in a header uses this text. + + ### `metadata.favicon.svg` + + - Type: `string` (file path) + - CLI: `--favicon-svg <PATH>` option + + Path to a SVG file to use as a favicon. + Path needs to be relative and resolved from the config file. + + ### `metadata.favicon.png` + + - Type: `string` (file path) + - CLI: `--favicon-png <PATH>` option + + Path to a PNG file to use as a favicon. + Path needs to be relative and resolved from the config file. + + ### `metadata.copyright` + + - Type: `string` + - CLI: `--copyright <TEXT>` option + - Required + + Copyright text to show in the generated website. + + ### `metadata.logoImage` + + - Type: `string` (file path) + - CLI: `--logo-image <PATH>` option + + Path to an image file to use as a website logo. + Path needs to be relative and resolved from the config file. + + ## Document options + ### `documents.defaultLanguage` + + - Type: `string` + - CLI: `--lang <TEXT>` option + - Default: `"en"` + + Default language for the generated website. + + ### `documents.languages.<directory>` + + - Type: `{ title: string; lang: string }` + + If a directory name matches to `<directory>`, the directory is treated as a language directory: the directory itself and its contents have different language than the parent one. + + ### `documents.resolveShortestPathWhenPossible` + + - Type: `boolean` + - CLI: `--shortest-path-when-possible` flag + + Enable support for Obsidian's "[[Ambiguous path resolution#Shortest path when possible|Shortest path when possible]]" link resolution. + + ### `documents.title.keepExtension` + + - Type: `boolean` + - CLI: `--keep-ext` flag + + By default, Macana use filename without file extension part as a document title. + If this option is enabled, Macana does not trim the file extension part. + + ## Markdown options + + ### `markdown.enabled` + + - Type: `boolean` + - Default: `true` + + Enable parsing of Markdown documents. + You can disable this from CLI via `--disable-markdown` flag. + + ### `markdown.yamlFrontmatter` + + - Type: `boolean` + - CLI: `--markdown-frontmatter` flag + + Enable parsing of YAML frontmatter in Markdown documents. + + ## JSONCanvas options + + ### `jsonCanvas.enabled` + + - Type: `boolean` + - Default: `true` + + Enable parsing of JSONCanvas documents. + You can disable this from CLI via `--disable-jsoncanvas` flag.
• docs/en/Roadmap.md
  • @@ -1,6 +1,6 @@
    --- createdAt: 2024-04-15T23:00:00+09:00 - updatedAt: 2024-05-25T00:22:00+09:00 + updatedAt: 2024-05-26T13:08:00+09:00 --- ## v1.0
  • @@ -23,7 +23,7 @@ ## v0.2
    - [x] CLI for opinionated build - [x] JSON/JSONC config for CLI - - [ ] Usage document for CLI + - [x] Usage document for CLI - [ ] Wikilink internal hash reference - [ ] Option to set base URL or path
• docs/en/Usage/CLI.md (new)
  • @@ -0,0 +1,17 @@
    + The easiest and cleanest way to use Macana is CLI script (`cli.ts`). + Pass a URL of the script to `deno run` and provide parameters. + Use `--help` to see parameters and arguments. + + ``` + $ deno run https://raw.githubusercontent.com/pocka/macana/03fa7ba42ea1d9d23c878a941811da105cebda96/cli.ts --help + ``` + + The CLI script accepts taking a config JSON/JSONC file via `--config` option. + Most of the generation options are available both as a CLI parameter and config field. + You need to grant `read` permission for the config JSON/JSONC file. + + ``` + $ deno run --allow-read=.macana.json https://raw.githubusercontent.com/pocka/macana/03fa7ba42ea1d9d23c878a941811da105cebda96/cli.ts --config .macana.json + ``` + + See [Config reference](/en/References/Config) for available options.
• docs/en/Usage/Deno module.md
  • @@ -1,5 +1,5 @@
    Macana is initially designed as a TypeScript module for Deno. - While this is tedious, you can tweak more options compared to the CLI. + While this is tedious, you can tweak more options compared to the [CLI usage](./CLI). ## System requirements