feat(website): auto generate oxfmt docs (#15985)

Corresponding PR: oxc-project/oxc-project.github.io#643

The next PR will get the json schema auto generated as well.

Author: Boshen

Cargo.lock

@@ -21,7 +21,7 @@ const PATHS_ERROR_MESSAGE: &str = "PATH must not contain \"..\"";
 #[derive(Debug, Clone, Bpaf)]
 #[bpaf(options, version(VERSION))]
 pub struct FormatCommand {
-    #[bpaf(external, fallback(OutputOptions::DefaultWrite))]
+    #[bpaf(external, fallback(OutputOptions::DefaultWrite), hide_usage)]
     pub output_options: OutputOptions,
     #[bpaf(external)]
     pub basic_options: BasicOptions,
@@ -31,7 +31,7 @@ pub struct FormatCommand {
     pub misc_options: MiscOptions,
     /// Single file, single path or list of paths.
     /// If not provided, current working directory is used.
-    /// Glob is supported only for exclude patterns like `'!**/fixtures/*.js'.
+    /// Glob is supported only for exclude patterns like `'!**/fixtures/*.js'`.
     // `bpaf(fallback)` seems to have issues with `many` or `positional`,
     // so we implement the fallback behavior in code instead.
     #[bpaf(positional("PATH"), many, guard(validate_paths, PATHS_ERROR_MESSAGE))]
@@ -65,14 +65,14 @@ pub struct BasicOptions {
 pub struct IgnoreOptions {
     /// Path to ignore file(s). Can be specified multiple times.
     /// If not specified, .gitignore and .prettierignore in the current directory are used.
-    #[bpaf(argument("PATH"), many)]
+    #[bpaf(argument("PATH"), many, hide_usage)]
     pub ignore_path: Vec<PathBuf>,
     /// Format code in node_modules directory (skipped by default)
     #[bpaf(switch, hide_usage)]
     pub with_node_modules: bool,
 }
 
-/// Miscellaneous
+/// Misc Options
 #[derive(Debug, Clone, Bpaf)]
 pub struct MiscOptions {
     /// Start language server protocol (LSP) server

apps/oxfmt/src/command.rs

@@ -247,13 +247,14 @@ watch-playground:
 # When testing changes to the website documentation, you may also want to run `dprint fmt --staged`
 # in the website directory.
 website path:
-  cargo run -p website -- linter-rules --table {{path}}/src/docs/guide/usage/linter/generated-rules.md --rule-docs {{path}}/src/docs/guide/usage/linter/rules --git-ref $(git rev-parse HEAD)
-  cargo run -p website -- linter-cli > {{path}}/src/docs/guide/usage/linter/generated-cli.md
-  cargo run -p website -- linter-schema-markdown > {{path}}/src/docs/guide/usage/linter/generated-config.md
+  cargo run -p website_linter rules --table {{path}}/src/docs/guide/usage/linter/generated-rules.md --rule-docs {{path}}/src/docs/guide/usage/linter/rules --git-ref $(git rev-parse HEAD)
+  cargo run -p website_linter cli > {{path}}/src/docs/guide/usage/linter/generated-cli.md
+  cargo run -p website_linter schema-markdown > {{path}}/src/docs/guide/usage/linter/generated-config.md
+  cargo run -p website_formatter cli > {{path}}/src/docs/guide/usage/formatter/generated-cli.md
 
 # Generate linter schema json for `npm/oxlint/configuration_schema.json`
 linter-schema-json:
-  cargo run -p website -- linter-schema-json > npm/oxlint/configuration_schema.json
+  cargo run -p website_linter schema-json > npm/oxlint/configuration_schema.json
 
 # Automatically DRY up Cargo.toml manifests in a workspace
 autoinherit:

justfile

@@ -0,0 +1,11 @@
+[package]
+name = "website_common"
+version = "0.0.0"
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lints]
+workspace = true
+
+[dependencies]

tasks/website/src/lib.rs

@@ -0,0 +1,62 @@
+/// Generate CLI documentation from bpaf-generated markdown.
+///
+/// Takes raw markdown from bpaf's `render_markdown()` and processes it into
+/// website-ready format with proper frontmatter and section headers.
+///
+/// # Arguments
+/// * `raw_markdown` - The markdown string from bpaf's render_markdown()
+/// * `tool_name` - The name of the tool (e.g., "oxlint", "oxfmt") used to strip the header
+/// * `gitignore_note_anchor` - Optional section header after which to insert the gitignore note
+///
+/// # Returns
+/// Processed markdown ready for the website
+#[expect(clippy::disallowed_methods)]
+pub fn generate_cli_docs(
+    raw_markdown: &str,
+    tool_name: &str,
+    gitignore_note_anchor: Option<&str>,
+) -> String {
+    // Remove the extra header
+    let header = format!("# {tool_name}\n");
+    let markdown = raw_markdown.trim_start_matches(header.as_str());
+
+    // Add ---\nsearch: false\n---\n at the top to prevent Vitepress from indexing this file.
+    let markdown = format!("---\nsearch: false\n---\n\n{markdown}");
+
+    // Hack usage line
+    let markdown = markdown.replacen("**Usage**:", "## Usage\n", 1);
+
+    let markdown = markdown
+        .split('\n')
+        .flat_map(|line| {
+            // Hack the bug on the line containing `###`
+            if line.contains("###") {
+                line.split("###").map(str::trim).chain(["\n"]).collect::<Vec<_>>()
+            } else {
+                vec![line]
+            }
+        })
+        .map(|line| {
+            // Make `** title **` to `## title`
+            if let Some(line) = line.strip_prefix("**")
+                && let Some(line) = line.strip_suffix("**")
+            {
+                format!("## {line}")
+            } else {
+                line.to_string()
+            }
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    // Add note about .gitignore only being respected inside Git repositories
+    if let Some(anchor) = gitignore_note_anchor {
+        let search_pattern = format!("\n\n## {anchor}\n");
+        let replacement = format!(
+            "\n\n> [!NOTE]\n> `.gitignore` is only respected inside a Git repository.\n\n## {anchor}\n"
+        );
+        markdown.replace(&search_pattern, &replacement)
+    } else {
+        markdown
+    }
+}

tasks/website/src/linter/cli.rs

@@ -0,0 +1,26 @@
+[package]
+name = "website_formatter"
+version = "0.0.0"
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lints]
+workspace = true
+
+[[bin]]
+name = "website_formatter"
+test = false
+doctest = false
+
+[dependencies]
+bpaf = { workspace = true, features = ["docgen"] }
+oxfmt = { path = "../../apps/oxfmt", default-features = false }
+pico-args = { workspace = true }
+website_common = { path = "../website_common" }
+
+[dev-dependencies]
+insta = { workspace = true }
+
+[package.metadata.cargo-shear]
+ignored = ["bpaf"]

tasks/website/src/linter/mod.rs

@@ -0,0 +1,29 @@
+use oxfmt::format_command;
+use website_common::generate_cli_docs;
+
+#[test]
+fn test_cli() {
+    let snapshot = generate_cli();
+    insta::with_settings!({ prepend_module_to_snapshot => false }, {
+        insta::assert_snapshot!(snapshot);
+    });
+}
+
+#[test]
+fn test_cli_terminal() {
+    let snapshot = oxfmt::format_command().run_inner(&["--help"]).unwrap_err().unwrap_stdout();
+    insta::with_settings!({ prepend_module_to_snapshot => false }, {
+        insta::assert_snapshot!(snapshot);
+    });
+}
+
+// <https://oxc.rs/docs/guide/usage/formatter/cli.html>
+#[expect(clippy::print_stdout)]
+pub fn print_cli() {
+    println!("{}", generate_cli());
+}
+
+fn generate_cli() -> String {
+    let markdown = format_command().render_markdown("oxfmt");
+    generate_cli_docs(&markdown, "oxfmt", None)
+}