# 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](https://www.jetify.com/docs/devbox/installing_devbox/). Then run

```bash
# in this folder

devbox shell
```

Now npx is available, next run

```bash
# 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:

![alt text](./_assets/techdocs.png)

## how this repo was generated

```bash
# 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

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

### verbosity level

```bash
 npx --loglevel silly techdocs-cli serve -v
 ```