@amritk/mjst 0.24.0 → 0.25.0

package/README.md

@@ -304,7 +304,7 @@ its own flags (and its own `--help`), independent of the generation flags above.
 
 ```bash
 # The prose reference: a heading, a type, the description and an example per
-# property, across as many pages as the schema's x-doc keyword declares
+# property, across as many pages as the schema's x-mjst keyword declares
 npx mjst markdown ./config.schema.json --out-dir ./docs
 
 # The other shape: one HTML table, spliced into an existing markdown file
@@ -315,7 +315,7 @@ npx mjst markdown ./config.schema.json --table --readme ./README.md
 | --- | --- |
 | `<schema>` | The JSON Schema to document (positional, required). |
 | `--out-dir` | Directory the prose reference pages are written to (default: the current directory). |
-| `--file` | Output path of the index page (default: the schema's `x-doc.file`, then `index.md`). |
+| `--file` | Output path of the index page (default: the schema's `x-mjst.file`, then `index.md`). |
 | `--title` | Page title (default: the schema's `title`). |
 | `--language` | Fence language for derived examples and literals (default: `json`). |
 | `--layout` | Default layout for nested properties: `headings` (default), `table`, or `none`. |
@@ -324,7 +324,7 @@ npx mjst markdown ./config.schema.json --table --readme ./README.md
 | `--type-label` | Whether every property heading gets its **Type:** line: `auto` (default) or `never`. Under `never` an enum lists its **Allowed values:** instead, since the label was the only other place they appeared. |
 | `--type-column` | When a property table renders its **Type** column: `auto` (default — only when a row fills it with something a reader could act on), `always`, or `never`. |
 | `--default-column` | When a property table renders its **Default** column: `auto` (default), `always`, or `never`. |
-| `--required-style` | How a property table says which properties are required: `marker` (default — `_required_` beside the name) or `column` (a **Required** column). |
+| `--required-style` | How a property table says which properties are required: `column` (default — a **Required** column), or any other text as a suffix right after a required name, as markdown or inline HTML — e.g. `"*"`, `" _required_"` or `"<br><sub><i>required</i></sub>"`. Appended exactly as written, so include a leading space if you want one. |
 | `--required-first` | List the required properties at the top of every table, the rest under them. |
 | `--table` | Render the HTML config table instead of the prose pages. |
 | `--readme` | Markdown file the table is spliced into (default: `README.md`). Requires `--table`. |

package/dist/markdown/help-text.d.ts

@@ -3,4 +3,4 @@
  * HELP_TEXT: the flag list is small and stable, and the test cross-checks that
  * every flag is listed.
  */
-export declare const MARKDOWN_HELP_TEXT = "mjst markdown \u2014 generate markdown documentation from a JSON Schema\n\nUsage:\n  mjst markdown <schema> --out-dir <dir> [options]\n  mjst markdown <schema> --table --readme <file>\n\nTwo shapes come out of the same schema. By default it writes the prose\nreference \u2014 a heading, a type, the description and an example per property,\nacross as many pages as the schema's x-doc keyword declares. With --table it\nrenders one HTML table instead and splices it into an existing markdown file\nbetween <!-- config-table-start --> and <!-- config-table-end -->, leaving the\nrest of that file alone.\n\nProse reference options:\n  --out-dir <dir>      Directory the pages are written to (default: the current directory)\n  --file <path>        Output path of the index page (default: the schema's x-doc.file, then index.md)\n  --title <text>       Page title (default: the schema's title)\n  --language <lang>    Fence language for derived examples and literals (default: json)\n  --layout <mode>      Default layout for nested properties: headings (default), table, or none\n  --sort <order>       Property order: schema (default) or alphabetical\n  --heading-level <n>  Heading level of the page title, 1-6 (default: 1)\n  --type-label <when>  Give every property heading its Type: line: auto (default) or\n                       never (an enum then lists its allowed values instead)\n\nProperty table options (the root x-doc.table, for every table on every page):\n  --type-column <when>     Render the Type column: auto (default), always, or never\n  --default-column <when>  Render the Default column: auto (default), always, or never\n  --required-style <how>   Say which properties are required: marker (default, beside\n                           the name) or column (a Required column)\n  --required-first         List the required properties at the top of every table\n\nTable options:\n  --table              Render the HTML config table instead of the prose pages\n  --readme <path>      Markdown file the table is spliced into (default: README.md)\n\nMisc:\n  --help, -h           Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";
+export declare const MARKDOWN_HELP_TEXT = "mjst markdown \u2014 generate markdown documentation from a JSON Schema\n\nUsage:\n  mjst markdown <schema> --out-dir <dir> [options]\n  mjst markdown <schema> --table --readme <file>\n\nTwo shapes come out of the same schema. By default it writes the prose\nreference \u2014 a heading, a type, the description and an example per property,\nacross as many pages as the schema's x-mjst keyword declares. With --table it\nrenders one HTML table instead and splices it into an existing markdown file\nbetween <!-- config-table-start --> and <!-- config-table-end -->, leaving the\nrest of that file alone.\n\nProse reference options:\n  --out-dir <dir>      Directory the pages are written to (default: the current directory)\n  --file <path>        Output path of the index page (default: the schema's x-mjst.markdown.file, then index.md)\n  --title <text>       Page title (default: the schema's title)\n  --language <lang>    Fence language for derived examples and literals (default: json)\n  --layout <mode>      Default layout for nested properties: headings (default), table, or none\n  --sort <order>       Property order: schema (default) or alphabetical\n  --heading-level <n>  Heading level of the page title, 1-6 (default: 1)\n  --type-label <when>  Give every property heading its Type: line: auto (default) or\n                       never (an enum then lists its allowed values instead)\n\nProperty table options (the root x-mjst.markdown.table, for every table on every page):\n  --type-column <when>     Render the Type column: auto (default), always, or never\n  --default-column <when>  Render the Default column: auto (default), always, or never\n  --required-style <how>   Say which properties are required: column (default, a\n                           Required column), or any other text as a suffix right\n                           after a required name, as markdown or inline HTML: \"*\",\n                           \" _required_\", \"<br><sub>required</sub>\"\n  --required-first         List the required properties at the top of every table\n\nTable options:\n  --table              Render the HTML config table instead of the prose pages\n  --readme <path>      Markdown file the table is spliced into (default: README.md)\n\nMisc:\n  --help, -h           Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";

package/dist/markdown/help-text.js

@@ -6,14 +6,14 @@ Usage:
 
 Two shapes come out of the same schema. By default it writes the prose
 reference \u2014 a heading, a type, the description and an example per property,
-across as many pages as the schema's x-doc keyword declares. With --table it
+across as many pages as the schema's x-mjst keyword declares. With --table it
 renders one HTML table instead and splices it into an existing markdown file
 between <!-- config-table-start --> and <!-- config-table-end -->, leaving the
 rest of that file alone.
 
 Prose reference options:
   --out-dir <dir>      Directory the pages are written to (default: the current directory)
-  --file <path>        Output path of the index page (default: the schema's x-doc.file, then index.md)
+  --file <path>        Output path of the index page (default: the schema's x-mjst.markdown.file, then index.md)
   --title <text>       Page title (default: the schema's title)
   --language <lang>    Fence language for derived examples and literals (default: json)
   --layout <mode>      Default layout for nested properties: headings (default), table, or none
@@ -22,11 +22,13 @@ Prose reference options:
   --type-label <when>  Give every property heading its Type: line: auto (default) or
                        never (an enum then lists its allowed values instead)
 
-Property table options (the root x-doc.table, for every table on every page):
+Property table options (the root x-mjst.markdown.table, for every table on every page):
   --type-column <when>     Render the Type column: auto (default), always, or never
   --default-column <when>  Render the Default column: auto (default), always, or never
-  --required-style <how>   Say which properties are required: marker (default, beside
-                           the name) or column (a Required column)
+  --required-style <how>   Say which properties are required: column (default, a
+                           Required column), or any other text as a suffix right
+                           after a required name, as markdown or inline HTML: "*",
+                           " _required_", "<br><sub>required</sub>"
   --required-first         List the required properties at the top of every table
 
 Table options:

package/dist/markdown/parse-markdown-args.d.ts

@@ -23,7 +23,10 @@ export type MarkdownArgs = {
     typeColumn?: DocTableColumn;
     /** When property tables render their Default column (`--default-column`). */
     defaultColumn?: DocTableColumn;
-    /** How property tables say which properties are required (`--required-style`). */
+    /**
+     * How property tables say which properties are required (`--required-style`):
+     * `column`, or any other text as a suffix after a required name.
+     */
     requiredStyle?: DocTableRequired;
     /** True when `--required-first` was passed: required properties head every table. */
     requiredFirst?: boolean;

package/dist/markdown/parse-markdown-args.js

@@ -17,7 +17,6 @@ const LAYOUTS = ["headings", "table", "none"];
 const SORTS = ["schema", "alphabetical"];
 const HEADING_TYPES = ["auto", "never"];
 const TABLE_COLUMNS = ["auto", "always", "never"];
-const REQUIRED_STYLES = ["marker", "column"];
 const toCamelCase = (key) => key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 const parseChoice = (flag, value, choices) => {
   const match = choices.find((choice) => choice === value);
@@ -65,8 +64,10 @@ const assignValue = (args, key, value) => {
     case "defaultColumn":
       args.defaultColumn = parseChoice("default-column", value, TABLE_COLUMNS);
       return;
+    // Free text on purpose: anything but `column` is the suffix itself, so
+    // there is no typo to catch — `*` is as valid as ` _required_`.
     case "requiredStyle":
-      args.requiredStyle = parseChoice("required-style", value, REQUIRED_STYLES);
+      args.requiredStyle = value;
       return;
     case "readme":
       args.readme = value;

package/dist/markdown/run.js

@@ -66,7 +66,7 @@ const run = async (argv) => {
     sort: args.sort,
     headingLevel: args.headingLevel,
     // Always passed: every member is optional, so the schema's own
-    // `x-doc.table` still decides whatever the flags left alone.
+    // `x-mjst.markdown.table` still decides whatever the flags left alone.
     table: {
       type: args.typeColumn,
       default: args.defaultColumn,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "engines": {
@@ -49,14 +49,14 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@amritk/adapters": "^0.6.5",
+    "@amritk/adapters": "^0.6.6",
     "@amritk/api": "^0.16.5",
-    "@amritk/asyncapi": "^0.3.3",
-    "@amritk/generate-examples": "^0.8.7",
-    "@amritk/generate-markdown": "^0.10.0",
-    "@amritk/helpers": "^0.23.1",
+    "@amritk/asyncapi": "^0.3.4",
+    "@amritk/generate-examples": "^0.8.8",
+    "@amritk/generate-markdown": "^0.11.0",
+    "@amritk/helpers": "^0.23.2",
     "@amritk/lint": "^0.6.1",
-    "@amritk/validation": "^0.3.0",
+    "@amritk/validation": "^0.3.1",
     "@amritk/resolve-refs": "^0.7.1",
     "@amritk/yaml": "^0.7.2",
     "fast-glob": "^3.3.2",