npm package: @neo4j-devtools/workspace-guides
Description: ## Previewing guides
Latest version: 0.0.74

# 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](https://workspace-preview.neo4j.io/workspace/example?enableFlag=nx%3Aexample-tab),

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

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

Example manifest:

```json
{
  "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:

  ```adoc
  == 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`.