NOTE: When we build techdocs-cli it copies the output embedded-techdocs-app bundle into the packages/techdocs-cli/dist which is then published with the @techdocs/cli npm package.

Running

# From the root of this repository run
# NOTE: This will build the embedded-techdocs-app and copy the output into the cli dist directory
yarn build --scope @techdocs/cli

# Now execute the binary
packages/techdocs-cli/bin/techdocs-cli

# ... or as a shell alias in ~/.zshrc or ~/.zprofile or ~/.bashrc or similar
export PATH=/path/to/backstage/packages/techdocs-cli/bin:$PATH

If you want to test live test changes to the packages/embedded-techdocs-app you can serve the app and run the CLI using the following commands:

# Open a shell to the embedded-techdocs-app directory
cd packages/embedded-techdocs-app

# Run the embedded-techdocs-app using dev mode
yarn start

# In another shell use the techdocs-cli from the root of this repo
yarn techdocs-cli:dev [...options]

Testing

Running unit tests requires mkdocs to be installed locally:

pip install mkdocs
pip install mkdocs-techdocs-core

Then run yarn test.

Use an example docs project

We have created an example documentation project and it's shipped with techdocs-container repository, for the purpose of local development. But you are free to create your own local test site. All it takes is a docs/index.md and mkdocs.yml in a directory.

git clone https://github.com/backstage/techdocs-container.git

cd techdocs-container/mock-docs

# To get a view of your docs in Backstage, use:
techdocs-cli serve

# To view the raw mkdocs site (without Backstage), use:
techdocs-cli serve:mkdocs