You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

105 lines
3.7 KiB

  1. # Docs Build Workflow
  2. The documentation for Tendermint Core is hosted at:
  3. - <https://docs.tendermint.com/>
  4. built from the files in this [`docs` directory for `master`](https://github.com/tendermint/tendermint/tree/master/docs)
  5. and other supported release branches.
  6. ## How It Works
  7. There is a [GitHub Actions workflow](https://github.com/tendermint/docs/actions/workflows/deployment.yml)
  8. in the `tendermint/docs` repository that clones and builds the documentation
  9. site from the contents of this `docs` directory, for `master` and for each
  10. supported release branch. Under the hood, this workflow runs `make build-docs`
  11. from the [Makefile](../Makefile#L214).
  12. The list of supported versions are defined in [`config.js`](./.vuepress/config.js),
  13. which defines the UI menu on the documentation site, and also in
  14. [`docs/versions`](./versions), which determines which branches are built.
  15. The last entry in the `docs/versions` file determines which version is linked
  16. by default from the generated `index.html`. This should generally be the most
  17. recent release, rather than `master`, so that new users are not confused by
  18. documentation for unreleased features.
  19. ## README
  20. The [README.md](./README.md) is also the landing page for the documentation
  21. on the website. During the Jenkins build, the current commit is added to the bottom
  22. of the README.
  23. ## Config.js
  24. The [config.js](./.vuepress/config.js) generates the sidebar and Table of Contents
  25. on the website docs. Note the use of relative links and the omission of
  26. file extensions. Additional features are available to improve the look
  27. of the sidebar.
  28. ## Links
  29. **NOTE:** Strongly consider the existing links - both within this directory
  30. and to the website docs - when moving or deleting files.
  31. Links to directories _MUST_ end in a `/`.
  32. Relative links should be used nearly everywhere, having discovered and weighed the following:
  33. ### Relative
  34. Where is the other file, relative to the current one?
  35. - works both on GitHub and for the VuePress build
  36. - confusing / annoying to have things like: `../../../../myfile.md`
  37. - requires more updates when files are re-shuffled
  38. ### Absolute
  39. Where is the other file, given the root of the repo?
  40. - works on GitHub, doesn't work for the VuePress build
  41. - this is much nicer: `/docs/hereitis/myfile.md`
  42. - if you move that file around, the links inside it are preserved (but not to it, of course)
  43. ### Full
  44. The full GitHub URL to a file or directory. Used occasionally when it makes sense
  45. to send users to the GitHub.
  46. ## Building Locally
  47. Make sure you are in the `docs` directory and run the following commands:
  48. ```bash
  49. rm -rf node_modules
  50. ```
  51. This command will remove old version of the visual theme and required packages. This step is optional.
  52. ```bash
  53. npm install
  54. ```
  55. Install the theme and all dependencies.
  56. ```bash
  57. npm run serve
  58. ```
  59. <!-- markdown-link-check-disable -->
  60. Run `pre` and `post` hooks and start a hot-reloading web-server. See output of this command for the URL (it is often <https://localhost:8080>).
  61. <!-- markdown-link-check-enable -->
  62. To build documentation as a static website run `npm run build`. You will find the website in `.vuepress/dist` directory.
  63. ## Search
  64. We are using [Algolia](https://www.algolia.com) to power full-text search. This uses a public API search-only key in the `config.js` as well as a [tendermint.json](https://github.com/algolia/docsearch-configs/blob/master/configs/tendermint.json) configuration file that we can update with PRs.
  65. ## Consistency
  66. Because the build processes are identical (as is the information contained herein), this file should be kept in sync as
  67. much as possible with its [counterpart in the Cosmos SDK repo](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md).