Backstage docs local

Take this repo and run a local Backstage harness when you want to edit documentation independently of a central docs repo.

For the PoC doc you first can prepare your docs here. Later on they will go into a central docs repo. Then the cebntral docs repo will render and publish the docs into a running backstage app in a eDF platform.

How to

You need nodejs and npx.

Use devbox if you want to keep your host clean

If you need a devboxed nodejs environment, have devbox installed. Then run

# in this folder

devbox shell

Now npx is available, next run

# in the repo root dir

# use backstage theme and frame
npx @techdocs/cli serve

# hint: add 'npx --force --libc=glibc' if the nodejs install hangs
# npx --verbose --force --libc=glibc @techdocs/cli serve

#use mkdocs theme
npx @techdocs/cli serve:mkdocs

and you will get

Output

You should see this screen:

how this repo was generated

# get mocked content from techdocs-container (backsatge/packages/techdocs-cli is too slow to clone)
mkdir tmp && cd tmp
git clone https://github.com/backstage/techdocs-container.git
cp -a mock-docs/* ..
cd ..
rm -rf tmp

# provide nodejs env
devbox init
devbox add yarn nodejs

Troubleshooting

When npm package download hangs

# install lcocally
npm install @techdocs/cli
node_modules/@techdocs/cli/bin/techdocs-cli serve

verbosity level

 npx --loglevel silly techdocs-cli serve -v

1.6 KiB Raw Blame History