|
1 | 1 | # How This Site Is Built |
| 2 | + |
| 3 | +## Hosting |
| 4 | + |
| 5 | +This documentation site is stored in the `gh-pages` branch and hosted on GitHub Pages. |
| 6 | + |
| 7 | +To create a standalone branch, separate from your source code branches, you can use the `--orphan` argument of git: |
| 8 | + |
| 9 | +```sh |
| 10 | +git switch --orphan gh-pages |
| 11 | +touch .nojekyll |
| 12 | +git add .nojekyll |
| 13 | +git commit -m "Initial commit for web site storing branch" |
| 14 | +git push --set-upstream origin gh-pages |
| 15 | +``` |
| 16 | + |
| 17 | +The `.nojekyll` file is used to prevent Jekyll from processing the files stored in this branch. |
| 18 | + |
| 19 | +Now, go to the project's `Settings` tab on GitHub to set up your Pages site. |
| 20 | + |
| 21 | +Under the `Build and deployment` section in the `Pages` section, |
| 22 | +set the `Source` to `Deploy from a branch` and the `Branch` to the root directory of the `gh-pages` branch. |
| 23 | + |
| 24 | +This will create an empty site that can be accessed even without a homepage. |
| 25 | + |
| 26 | +## Directory Structure |
| 27 | + |
| 28 | +Here’s the file structure of the `gh-pages` branch, which is also this documentation site: |
| 29 | + |
| 30 | +``` |
| 31 | +gh-pages |
| 32 | + |-index.html |
| 33 | + |-versions.json |
| 34 | + |-.nojekyll |
| 35 | + |-dev |
| 36 | + | |-index.html |
| 37 | + | |-modules.html |
| 38 | + | |-.nojekyll |
| 39 | + | |-functions |
| 40 | + | | |-index.load.html |
| 41 | + | |-documents |
| 42 | + | | |-example.html |
| 43 | + | |-modules |
| 44 | + | | |-index.html |
| 45 | + | |-assets |
| 46 | + | | |-icons.js |
| 47 | + | | |-hierarchy.js |
| 48 | + | | |-highlight.css |
| 49 | + | | |-version-select.css |
| 50 | + | | |-main.js |
| 51 | + | | |-version-select.js |
| 52 | + | | |-navigation.js |
| 53 | + | | |-style.css |
| 54 | + | | |-search.js |
| 55 | + | | |-icons.svg |
| 56 | + |-v1 |
| 57 | + | |-index.html |
| 58 | + | |-modules.html |
| 59 | + | |-.nojekyll |
| 60 | + | |-functions |
| 61 | + | | |-index.load.html |
| 62 | + | |-documents |
| 63 | + | | |-example.html |
| 64 | + | |-modules |
| 65 | + | | |-index.html |
| 66 | + | |-assets |
| 67 | + | | |-icons.js |
| 68 | + | | |-hierarchy.js |
| 69 | + | | |-highlight.css |
| 70 | + | | |-version-select.css |
| 71 | + | | |-main.js |
| 72 | + | | |-version-select.js |
| 73 | + | | |-navigation.js |
| 74 | + | | |-style.css |
| 75 | + | | |-search.js |
| 76 | + | | |-icons.svg |
| 77 | + |-.git |
| 78 | +``` |
| 79 | + |
| 80 | +### Document for multiple versions |
| 81 | + |
| 82 | +This document contains multiple versions of the website. |
| 83 | + |
| 84 | +The first-level directories, `dev` and `v1`, represent two different versions. |
| 85 | + |
| 86 | +- When the `master` branch has a new commit, |
| 87 | +a GitHub workflow generates the updated document and commits it to the `dev` directory in the `gh-pages` branch. |
| 88 | +- When a new version `1.*.*` is released, |
| 89 | +the generated document is checked into the `v1` directory. |
| 90 | + |
| 91 | +Once the content in the `gh-pages` branch changes, |
| 92 | +GitHub deploys the updated assets to GitHub Pages. |
| 93 | + |
| 94 | +### index.html |
| 95 | + |
| 96 | +The website needs to redirect the browser to the default version when the user accesses the root homepage. |
| 97 | +Since GitHub Pages doesn’t allow you to configure redirect responses, |
| 98 | +we use the `<meta>` tag in the [index.html](https://github.com/jameslan/typedoc-plugin-version-select/blob/gh-pages/index.html#L7) head to make the browser jump to another URL. |
| 99 | + |
| 100 | +This file needs to be manually updated when the default version changes. |
| 101 | +For example, a new major version is released and stored in a new directory, |
| 102 | +so it becomes the new default version. |
| 103 | + |
| 104 | +### versions.json |
| 105 | + |
| 106 | +[versions.json](https://github.com/jameslan/typedoc-plugin-version-select/blob/gh-pages/versions.json) contains the configuration of the content of the version select dropdown menu. |
| 107 | + |
| 108 | +## GitHub Action |
| 109 | + |
| 110 | +This project uses [a GitHub workflow](https://github.com/jameslan/typedoc-plugin-version-select/blob/master/.github/workflows/doc.yml) to automatically generate and check-in the document site. |
| 111 | + |
| 112 | +### Triggering |
| 113 | + |
| 114 | +The workflow is triggered when a new commit is pushed to the `master` branch or a new release is published. |
| 115 | + |
| 116 | +### Permission |
| 117 | + |
| 118 | +Since we need to commit to the `gh-pages` branch and push, |
| 119 | +we require write permission. |
| 120 | + |
| 121 | +### Steps |
| 122 | + |
| 123 | +- In the step `Checkout the site branch`, we check out `gh-pages` branch into directory `site`. |
| 124 | +- In the step `Build doc`, the documents are built into `docs` directory. |
| 125 | +Due to our directory structure, |
| 126 | +the default value of option `versionSpecHRef` works, so we don't need to customize it. |
| 127 | +- In the step `Find variables`, shell script is used to set up some workflow variables |
| 128 | +- In the `Find variables` step, a shell script is employed to set up essential workflow variables, |
| 129 | +including the version (directory name) and commit message. |
| 130 | +This step is identified by the id `vars` to facilitate referencing of these variables as `steps.vars.outputs.*`. |
| 131 | +- Next, in the `Build site` step, the newly generated documents replace the subdirectory. |
| 132 | +- Finally, in the `Commit to site branch` step, the changes are committed and pushed to the `gh-pages` branch. |
| 133 | + |
| 134 | +By executing these steps, the documentation site is automatically updated in accordance with the latest commit. |
| 135 | + |
| 136 | +However, it’s important to note that this workflow does not update the `versions.json` file. |
| 137 | +Therefore, manual updates to this file are necessary when required. |
0 commit comments