Guides Parser

Previewing guides

To preview AsciiDoc guides:

• Run the following command in the directory where you're editing the AsciiDoc guides:

npx @neo4j-devtools/workspace-guides -w

• Open the Example tab in Workspace Preview,

• Scroll to Playlist Preview -> Manifest origin override, fill the text field with the server's URL (the default is http://localhost:4000/).

• Click Update URL and the guides available for preview will be listed in the Guides section.

• If you add/rename guides you might need to click the Refetch manifest button for them to appear.

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: generated tmp directory] 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
-u, --img-base-url=<value> Base URL where images are hosted.
--dry-run

DESCRIPTION
Parse Workspace guides from Adoc to JSON.

EXAMPLES
$ parse-guides --watch

$ parse-guides --watch -u "https://neo4j-graph-examples.github.io/movies/documentation/img/"

$ 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.