@neo4j-devtools/workspace-guides

Guides Parser

Usage

USAGE
$ parse-guides [-i INPUT_DIR_PATH] [-o OUTPUT_DIR_PATH] [--root-url ROOT_URL] [-w] [-m PATH_TO_MANIFEST]

FLAGS
-i, --input-dir=<value>  [default: .] Path to directory containing .adoc guides
-o, --output-dir=<value> [default: json-guides] Path to directory that will contain .json guides
--root-url=<value>       Base URL that output files will be served from
-w, --watch              Watch the input directory for changes and automatically
rebuild guides, also hosts the guides.
-m, --manifest=<value>   Path to guides manifest
--dry-run

DESCRIPTION
Parse Workspace guides from Adoc to JSON.

EXAMPLES
$ parse-guides --watch

$ parse-guides -i path/to/guides/dir -o output/path --watch

$ parse-guides -m path/to/manifest.json

$ parse-guides -m path/to/manifest.json -o output/path

NOTES
The script searches for guides recursively in the input directory, and the path
is be preserved in the output directory.

When specifying a manifest file the `--input-dir` flag is ignored.

Guides manifest

The guides manifest must be a JSON file containing a mapping of IDs and the corresponding url for the adoc guide and an optional base URL for the images contained in the guide. The typing for the manifest is the following.

type GuideManifest = Record<string, { url: string; imgBaseUrl?: string }>;

Example manifest:

{
  "movies": {
    "url": "https://raw.githubusercontent.com/neo4j-graph-examples/movies/main/documentation/movies.workspace.adoc",
    "imgBaseUrl": "https://raw.githubusercontent.com/neo4j-graph-examples/movies/main/documentation/img/"
  },
  "recommendations": {
    "url": "https://raw.githubusercontent.com/neo4j-graph-examples/recommendations/main/documentation/recommendations.workspace.adoc",
    "imgBaseUrl": "https://raw.githubusercontent.com/neo4j-graph-examples/recommendations/main/documentation/img/"
  }
}

Root URL

Image assets used in guides are copied to output directory, to avoid conflicts, they are placed in folders named after guide ID of the guide that uses them. To use correct absolute URLs --root-url CLI argument must be specified.

Example

Prerequisites:

• a guide file named <input-dir>/guide.workspace.adoc with following contents:

  == Guide Title
  
  image::asset.svg[]
  

• a GitHub repository neo4j/guides used to host JSON output on GitHub Pages.

GitHub Pages URLs format is https://<owner>.github.io/<repository> hence root URL will be https://neo4j.github.io/guides:

parse-guides -i <input-dir> -o <output-dir> --root-url https://neo4j.github.io/guides

Result:

• guide JSON is placed at <output-dir>/guide.json;
• asset is placed at <output-dir>/guide/asset.svg;
• asset URL inside the guide JSON is https://neo4j.github.io/guides/guide/asset.svg.