techdocs-cli

Usage

See techdocs-cli usage docs.

Development

Set up locally

To setup the project for local development, clone this repository, install dependencies and build a local version of the CLI.

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

cd techdocs-cli/

yarn install

yarn build

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.

If you're changing files inside @backstage/techdocs-common locally and want to run it locally with techdocs-cli you can run:

cd backstage/packages/techdocs-common`
yarn link

The backstage folder above is from the main Backstage repo

And then inside the techdocs-cli repo:

yarn link "@backstage/techdocs-common"

When you're done, remember to unlink the package so you can use the published version again:

yarn unlink "@backstage/techdocs-common" && yarn install --force

Running

You can now run the CLI:

# execute the CLI from the root of the repo
yarn cli

# or using the techdoc-cli binary directly
packages/techdocs-cli/bin/techdocs-cli

# ... or as a shell alias in ~/.zshrc or ~/.zprofile or ~/.bashrc or similar
export PATH=/path/to/repo/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
yarn start:app

# In another shell use the techdocs-cli
yarn 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

Contributing

We love having contributions, so if you want to contribute, please:

1. Create a new Pull Request from your branch to the main

2. If you want to include your changes in the next version bump, run:

yarn changeset

3. Choose a package, semver version, add a summary of the changes and press ENTER

4. This script will create a new markdown file in the .changeset folder

   Not sure what this means? Click here to learn what changesets are

5. Commit the changeset along with your PR changes.

Release

This repository uses changesets for a more automated release process. All changes to the packages of this repository, packages/embedded-techdocs-app and packages/techdocs-cli should have changesets added along with each change.

Once you decide you want to do a release:

Manual release

1. yarn changeset version This consumes all changesets, and updates to the most appropriate semver version based on those changesets. It also writes changelog entries for each consumed changeset.

When you have verified the version and changelogs looks as expected, you can publish the new version:

2. yarn changeset publish

Automated release

We have automated these two steps in our main workflow.

1. The main.yml workflow opens a new PR for you with the package versions and updated changelogs.

2. This PR can then be merged and if the new version is not published to NPM, the publish step in the main.yml workflow will get triggered and publish the new version for you.

Note: The Backstage app and plugins versions are fixed in the packages/embedded-techdocs-app mono-repo. So @backstage/plugin-techdocs version may need upgrading from time to time if significant APIs are changed.