3976a99771
* Base fork for 4.3 docs * [docs] external email identities and Kube Users (#3628) * Base fork for 4.3 docs * [docs] external email identities and Kube Users (#3628) * Remove trailing whitespace from docs files Some editors will do this automatically on save. This causes a lot of diffs when editing the docs in such an editor. Clean them up once now and we'll try to keep it tidy going forward. * Add make rules for docs whitespace and milv docs-test-whitespace: checks for trailing whitespace in all .md files under docs/. docs-fix-whitespace: removes trailing whitespace in all .md files under docs/. docs-test-links: runs milv in all docs/ subdirectories that have milv.config.yaml. docs-test: runs whitespace and links tests, used during `make docs` * Document the new `--use-local-ssh-agent` flag for tsh The flag is used to bypass the local SSH agent even when it's running. Specifically, this helps with agents that don't support certs. The flag was added in #3721 * Remove pam_script.so docs from SSH PAM page With #3725 we now populate teleport-specific env vars in a way that's accessible to `pam_exec.so`. There's no longer any reason to install pam_script.so separately and duplicate our docs. Updates #3692 * Using the correct --insecure-no-tls flag * Run docs-fix-whitespace make rule in a busybox container * Fixes #3414 Co-authored-by: Andrew Lytvynov <andrew@gravitational.com> Co-authored-by: Gus Luxton <gus@gravitational.com> Co-authored-by: Steven Martin <steven@gravitational.com> Co-authored-by: Gus Luxton <webvictim@gmail.com>
2.3 KiB
Teleport Docs
Teleport docs are built using mkdocs and hosted as a bunch of static files in S3.
Look at build.sh script to see how it works.
To Publish New Version
- Update build.sh.
- Update theme/scripts.html to add a new version to the docVersions array of versions
- Create a new YAML file, like
5.5.1.yamlif you are releasing version 5.5.1
Deploying
Teleport docs are published using a private web repository.
See web/README.md for more info.
Running Locally
We recommend using Docker to run and build the docs.
make run-docs will run the docs and setup a livereload server for easy previewing of changes.
make docs will build the docs, so they are ready to ship to production.
Tools used to build the Docs
Teleport Docs are made with MkDocs and a few markdown extensions, First time users will need to install MkDocs https://www.mkdocs.org/#installation.
To run the latest version of the docs on http://127.0.0.1:8000:
$ ./run.sh
To run a specific version of the docs:
$ mkdocs serve --config-file 1.3.yaml
Checking for bad links
Install milv (Markdown Internal Link Validator) using go get -u -v github.com/magicmatatjahu/milv.
Change to the appropriate base directory, then run milv and make sure it reports no errors:
$ cd docs/4.1`
$ milv
NO ISSUES :-)
milv will validate all internal and external links by default. The external link checking can take 30 seconds or so to run. You can run milv -v to see all outgoing requests if you think it's taking too long. You can also skip external link checking altogether with milv --ignore-external - this can be useful if you're rapidly trying to fix internal links.
Make sure that you fix any broken links or errors before committing your changes!
If there is a genuine false positive or case where milv is failing to parse a link correctly but it does work (and you have validated this using make run-docs or mkdocs serve) then you can add a whitelist under the appropriate section in milv.config.yaml and commit this back to the repo.