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.

104 lines
3.1 KiB

  1. # Docs Build Workflow
  2. The documentation for Tendermint Core is hosted at:
  3. - https://tendermint.com/docs/ and
  4. - https://tendermint-staging.interblock.io/docs/
  5. built from the files in this (`/docs`) directory for
  6. [master](https://github.com/tendermint/tendermint/tree/master/docs)
  7. and [develop](https://github.com/tendermint/tendermint/tree/develop/docs),
  8. respectively.
  9. ## How It Works
  10. There is a CircleCI job listening for changes in the `/docs` directory, on both
  11. the `master` and `develop` branches. Any updates to files in this directory
  12. on those branches will automatically trigger a website deployment. Under the hood,
  13. the private website repository has a `make build-docs` target consumed by a CircleCI job in that repo.
  14. ## README
  15. The [README.md](./README.md) is also the landing page for the documentation
  16. on the website. During the Jenkins build, the current commit is added to the bottom
  17. of the README.
  18. ## Config.js
  19. The [config.js](./.vuepress/config.js) generates the sidebar and Table of Contents
  20. on the website docs. Note the use of relative links and the omission of
  21. file extensions. Additional features are available to improve the look
  22. of the sidebar.
  23. ## Links
  24. **NOTE:** Strongly consider the existing links - both within this directory
  25. and to the website docs - when moving or deleting files.
  26. Links to directories *MUST* end in a `/`.
  27. Relative links should be used nearly everywhere, having discovered and weighed the following:
  28. ### Relative
  29. Where is the other file, relative to the current one?
  30. - works both on GitHub and for the VuePress build
  31. - confusing / annoying to have things like: `../../../../myfile.md`
  32. - requires more updates when files are re-shuffled
  33. ### Absolute
  34. Where is the other file, given the root of the repo?
  35. - works on GitHub, doesn't work for the VuePress build
  36. - this is much nicer: `/docs/hereitis/myfile.md`
  37. - if you move that file around, the links inside it are preserved (but not to it, of course)
  38. ### Full
  39. The full GitHub URL to a file or directory. Used occasionally when it makes sense
  40. to send users to the GitHub.
  41. ## Building Locally
  42. To build and serve the documentation locally, run:
  43. ```
  44. # from this directory
  45. npm install -g vuepress
  46. ```
  47. NOTE: the command may require `sudo`.
  48. then change the following line in the `.vuepress/config.js`:
  49. ```
  50. base: "/docs/",
  51. ```
  52. to:
  53. ```
  54. base: "/",
  55. ```
  56. Finally, go up one directory to the root of the repo and run:
  57. ```
  58. # from root of repo
  59. vuepress build docs
  60. cd dist/docs
  61. python -m SimpleHTTPServer 8080
  62. ```
  63. then navigate to localhost:8080 in your browser.
  64. ## Search
  65. 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.
  66. ## Consistency
  67. Because the build processes are identical (as is the information contained herein), this file should be kept in sync as
  68. much as possible with its [counterpart in the Cosmos SDK repo](https://github.com/cosmos/cosmos-sdk/blob/develop/docs/DOCS_README.md).