hongdown 0.1.0-dev.11

package/README.md

@@ -0,0 +1,286 @@
+Hongdown
+========
+
+[![crates.io][crates.io badge]][crates.io]
+[![npm][npm badge]][npm]
+[![GitHub Actions][GitHub Actions badge]][GitHub Actions]
+
+Hongdown is a Markdown formatter that enforces [Hong Minhee's Markdown style]
+conventions.  The formatter is implemented in Rust using the [Comrak] library
+for parsing.  It produces consistently formatted Markdown output following
+a distinctive style used across multiple projects including [Fedify], [LogTape],
+and [Optique].
+
+[crates.io badge]: https://img.shields.io/crates/v/hongdown?logo=rust
+[crates.io]: https://crates.io/crates/hongdown
+[npm badge]: https://img.shields.io/npm/v/hongdown?logo=npm
+[npm]: https://www.npmjs.com/package/hongdown
+[GitHub Actions badge]: https://github.com/dahlia/hongdown/actions/workflows/main.yaml/badge.svg
+[GitHub Actions]: https://github.com/dahlia/hongdown/actions/workflows/main.yaml
+[Hong Minhee's Markdown style]: ./AGENTS.md#markdown-style-guide
+[Comrak]: https://comrak.ee/
+[Fedify]: https://fedify.dev/
+[LogTape]: https://logtape.org/
+[Optique]: https://optique.dev/
+
+
+Installation
+------------
+
+### npm
+
+~~~~ bash
+npm install -g hongdown
+~~~~
+
+### mise
+
+~~~~ bash
+mise use github:dahlia/hongdown
+~~~~
+
+### Cargo
+
+~~~~ bash
+cargo install hongdown
+~~~~
+
+### Pre-built binaries
+
+Pre-built binaries for Linux, macOS, and Windows are available on the
+[GitHub Releases] page.
+
+[GitHub Releases]: https://github.com/dahlia/hongdown/releases
+
+
+Usage
+-----
+
+### Basic usage
+
+~~~~ bash
+# Format a file and print to stdout
+hongdown input.md
+
+# Format a file in place
+hongdown --write input.md
+hongdown -w input.md
+
+# Format multiple files
+hongdown -w *.md
+
+# Check if files are formatted (exit 1 if not)
+hongdown --check input.md
+hongdown -c input.md
+
+# Show diff of formatting changes
+hongdown --diff input.md
+hongdown -d input.md
+
+# Read from stdin
+echo "# Hello" | hongdown
+hongdown --stdin < input.md
+
+# Custom line width
+hongdown --line-width 100 input.md
+~~~~
+
+### Disable directives
+
+Hongdown supports special HTML comments to disable formatting for specific
+sections of your document:
+
+~~~~ markdown
+<!-- hongdown-disable-file -->
+This entire file will not be formatted.
+~~~~
+
+~~~~ markdown
+<!-- hongdown-disable-next-line -->
+This   line   preserves   its   spacing.
+
+The next line will be formatted normally.
+~~~~
+
+~~~~ markdown
+<!-- hongdown-disable-next-section -->
+Everything here is preserved as-is
+until the next heading (h1 or h2).
+
+Next heading
+------------
+
+This section will be formatted normally.
+~~~~
+
+~~~~ markdown
+<!-- hongdown-disable -->
+This section is not formatted.
+<!-- hongdown-enable -->
+This section is formatted again.
+~~~~
+
+### Configuration file
+
+Hongdown looks for a *.hongdown.toml* file in the current directory and
+parent directories.  You can also specify a configuration file explicitly
+with the `--config` option.
+
+Below is an example configuration with all available options and their
+default values:
+
+~~~~ toml
+# File patterns (glob syntax)
+include = []              # Files to format (default: none, specify on CLI)
+exclude = []              # Files to skip (default: none)
+
+# Formatting options
+line_width = 80           # Maximum line width (default: 80)
+
+[heading]
+setext_h1 = true          # Use === underline for h1 (default: true)
+setext_h2 = true          # Use --- underline for h2 (default: true)
+
+[list]
+unordered_marker = "-"    # "-", "*", or "+" (default: "-")
+leading_spaces = 1        # Spaces before marker (default: 1)
+trailing_spaces = 2       # Spaces after marker (default: 2)
+indent_width = 4          # Indentation for nested items (default: 4)
+
+[ordered_list]
+odd_level_marker = "."    # "." or ")" at odd nesting levels (default: ".")
+even_level_marker = ")"   # "." or ")" at even nesting levels (default: ")")
+pad = "start"             # "start" or "end" for number alignment (default: "start")
+indent_width = 4          # Indentation for nested items (default: 4)
+
+[code_block]
+fence_char = "~"          # "~" or "`" (default: "~")
+min_fence_length = 4      # Minimum fence length (default: 4)
+space_after_fence = true  # Space between fence and language (default: true)
+~~~~
+
+When `include` patterns are configured, you can run Hongdown without
+specifying files:
+
+~~~~ bash
+# Format all files matching include patterns
+hongdown --write
+
+# Check all files matching include patterns
+hongdown --check
+~~~~
+
+CLI options override configuration file settings:
+
+~~~~ bash
+# Use config file but override line width
+hongdown --line-width 100 input.md
+
+# Use specific config file
+hongdown --config /path/to/.hongdown.toml input.md
+~~~~
+
+
+Style rules
+-----------
+
+Hongdown enforces the following conventions:
+
+### Headings
+
+ -  Level 1 and 2 use Setext-style (underlined with `=` or `-`)
+ -  Level 3+ use ATX-style (`###`, `####`, etc.)
+
+~~~~ markdown
+Document Title
+==============
+
+Section
+-------
+
+### Subsection
+~~~~
+
+### Lists
+
+ -  Unordered lists use ` -  ` (space-hyphen-two spaces)
+ -  Ordered lists use `1.` format
+ -  4-space indentation for nested items
+
+~~~~ markdown
+ -  First item
+ -  Second item
+     -  Nested item
+~~~~
+
+### Code blocks
+
+ -  Fenced with four tildes (`~~~~`)
+ -  Language identifier on the opening fence
+
+~~~~~ text
+~~~~ rust
+fn main() {
+    println!("Hello, world!");
+}
+~~~~
+~~~~~
+
+### Line wrapping
+
+ -  Lines wrap at approximately 80 display columns
+ -  East Asian wide characters are counted as 2 columns
+ -  Long words that cannot be broken are preserved
+
+### Links
+
+ -  External URLs are converted to reference-style links
+ -  References are placed at the end of each section
+ -  Relative/local URLs remain inline
+
+~~~~ markdown
+See the [documentation] for more details.
+
+[documentation]: https://example.com/docs
+~~~~
+
+### Tables
+
+ -  Pipes are aligned accounting for East Asian wide characters
+ -  Minimum column width is maintained
+
+See the [*Markdown style guide*] for more detailed style conventions.
+
+[*Markdown style guide*]: ./AGENTS.md#markdown-style-guide
+
+
+Library usage
+-------------
+
+Hongdown can also be used as a Rust library:
+
+~~~~ rust
+use hongdown::{format, Options};
+
+let input = "# Hello World\nThis is a paragraph.";
+let options = Options::default();
+let output = format(input, &options).unwrap();
+println!("{}", output);
+~~~~
+
+
+Etymology
+---------
+
+The name *Hongdown* is a portmanteau of *Hong* (from Hong Minhee, the author)
+and *Markdown*.  It also sounds like the Korean word *hongdapda* (홍답다),
+meaning “befitting of Hong” or “Hong-like.”
+
+
+License
+-------
+
+Distributed under the [GPL-3.0-or-later].  See *[LICENSE]* for more information.
+
+[GPL-3.0-or-later]: https://www.gnu.org/licenses/gpl-3.0.html
+[LICENSE]: ./LICENSE

package/bin/hongdown.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+const PLATFORMS = {
+  "darwin-arm64": "@hongdown/darwin-arm64",
+  "darwin-x64": "@hongdown/darwin-x64",
+  "linux-arm64": "@hongdown/linux-arm64",
+  "linux-x64": "@hongdown/linux-x64",
+  "win32-arm64": "@hongdown/win32-arm64",
+  "win32-x64": "@hongdown/win32-x64",
+};
+
+const platformKey = `${process.platform}-${process.arch}`;
+const packageName = PLATFORMS[platformKey];
+
+if (!packageName) {
+  console.error(`Unsupported platform: ${platformKey}`);
+  process.exit(1);
+}
+
+try {
+  const binName = process.platform === "win32" ? "hongdown.exe" : "hongdown";
+  const binPath = require.resolve(`${packageName}/bin/${binName}`);
+  const result = spawnSync(binPath, process.argv.slice(2), {
+    stdio: "inherit",
+  });
+  process.exit(result.status ?? 1);
+} catch (e) {
+  console.error(`Failed to run hongdown: ${e.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "hongdown",
+  "version": "0.1.0-dev.11+be401b59",
+  "type": "module",
+  "description": "A Markdown formatter that enforces Hong Minhee's Markdown style conventions",
+  "license": "GPL-3.0-or-later",
+  "author": "Hong Minhee <hong@minhee.org>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/hongdown.git"
+  },
+  "homepage": "https://github.com/dahlia/hongdown",
+  "keywords": [
+    "markdown",
+    "formatter",
+    "linter",
+    "style"
+  ],
+  "bin": {
+    "hongdown": "bin/hongdown.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@hongdown/darwin-arm64": "0.1.0-dev.11+be401b59",
+    "@hongdown/darwin-x64": "0.1.0-dev.11+be401b59",
+    "@hongdown/linux-arm64": "0.1.0-dev.11+be401b59",
+    "@hongdown/linux-x64": "0.1.0-dev.11+be401b59",
+    "@hongdown/win32-arm64": "0.1.0-dev.11+be401b59",
+    "@hongdown/win32-x64": "0.1.0-dev.11+be401b59"
+  }
+}