├── README.md └── docs └── how-to-create-a-new-repo.md /README.md: -------------------------------------------------------------------------------- 1 | WangDoc 的帮助文档 2 | -------------------------------------------------------------------------------- /docs/how-to-create-a-new-repo.md: -------------------------------------------------------------------------------- 1 | # Wangdoc 新增仓库的流程 2 | 3 | ## Git 初始化 4 | 5 | 新建一个文档仓库，命名为`xxx-tutorial`。其中，`xxx`为该仓库的主题，比如`javascript-tutorial`。 6 | 7 | 将这个仓库进行 Git 初始化。 8 | 9 | ```bash 10 | $ git init 11 | ``` 12 | 13 | 然后，新建`.gitignore`，写入下面的内容。 14 | 15 | ```bash 16 | node_modules/ 17 | dist/ 18 | package-lock.json 19 | ``` 20 | 21 | ## npm 模块初始化 22 | 23 | 第一步，新建`package.json`。 24 | 25 | ```bash 26 | $ npm init -y 27 | ``` 28 | 29 | 第二步，修改`package.json`。 30 | 31 | `package.json`的`license`字段可以改成创意共享许可证（署名-相同方式共享）。 32 | 33 | ```javascript 34 | "license": "CC-BY-SA-4.0", 35 | ``` 36 | 37 | `author`字段改成“Ruan Yifeng”。 38 | 39 | `scripts`字段下插入如下脚本。 40 | 41 | ```javascript 42 | "scripts": { 43 | "build": "loppo --site \"[xxx] 教程\" --id [xxx] --theme wangdoc", 44 | "build-and-commit": "npm run build && npm run commit", 45 | "commit": "gh-pages --dist dist --dest dist/[xxx] --branch master --repo git@github.com:wangdoc/website.git", 46 | "chapter": "loppo chapter", 47 | "server": "loppo server" 48 | }, 49 | ``` 50 | 51 | 注意，要把脚本里面的`[xxx]`替换掉，共有三处。 52 | 53 | 第三步，安装依赖。需要以下三个库。 54 | 55 | - loppo 56 | - loppo-theme-wangdoc 57 | - gh-pages 58 | 59 | ```bash 60 | $ npm install --save loppo@latest loppo-theme-wangdoc@latest gh-pages 61 | ``` 62 | 63 | 为了确保安装的是最新版本，可以打开`package.json`，将`loppo`和`loppo-theme-wangdoc`的版本改成`latest`，然后执行一下`npm update`。 64 | 65 | ```bash 66 | $ npm update 67 | ``` 68 | 69 | 第四步，运行`npm run chapter`，生成目录文件`chapters.yml`。 70 | 71 | ```bash 72 | $ npm run chapter 73 | ``` 74 | 75 | 编辑`chapters.yml`文件，使得目录编排正确。 76 | 77 | 然后，运行`npm run build`，生成`loppo.yml`文件。 78 | 79 | 第五步，本地运行`npm run server`，看看构建是否正确。 80 | 81 | 第六步，写入代码仓库。 82 | 83 | ```bash 84 | $ git add -A 85 | $ git commit -m "feat: first commit" 86 | ``` 87 | 88 | ## GitHub 仓库 89 | 90 | 在 GitHub 的 wangdoc 团队下新建仓库，然后推送本地仓库。 91 | 92 | ## GitHub Actions 93 | 94 | 第一步，新建子目录`.github/workflows`。 95 | 96 | ```bash 97 | $ mkdir -p .github/workflows 98 | ``` 99 | 100 | 第三步，检查仓库设置的`secrets`里面，有没有`WANGDOC_BOT_TOKEN`这一项。如果没有，需要为 wangdoc-bot 生成一个 TOKEN 并添加在`secrets`里面。 101 | 102 | 第三步，新建配置文件`wangdoc.yml`。 103 | 104 | ```bash 105 | $ vi .github/workflows/wangdoc.yml 106 | ``` 107 | 108 | 文件内容如下。 109 | 110 | ```yaml 111 | name: [XXX] tutorial CI 112 | on: 113 | push: 114 | branches: 115 | - main 116 | 117 | jobs: 118 | page-generator: 119 | name: Generating pages 120 | runs-on: ubuntu-latest 121 | steps: 122 | - name: Checkout 123 | uses: actions/checkout@v4 124 | with: 125 | persist-credentials: false 126 | - name: Setup Node.js 127 | uses: actions/setup-node@v4 128 | with: 129 | node-version: 'latest' 130 | - name: Install dependencies 131 | run: npm install 132 | - name: Build pages 133 | run: npm run build 134 | - name: Deploy to website 135 | uses: JamesIves/github-pages-deploy-action@v4 136 | with: 137 | git-config-name: wangdoc-bot 138 | git-config-email: yifeng.ruan@gmail.com 139 | repository-name: wangdoc/website 140 | token: ${{ secrets.WANGDOC_BOT_TOKEN }} 141 | branch: master # The branch the action should deploy to. 142 | folder: dist # The folder the action should deploy. 143 | target-folder: dist/[xxx] 144 | clean: true # Automatically remove deleted files from the deploy branch 145 | commit-message: update from [xxx] tutorial 146 | ``` 147 | 148 | 注意： 149 | 150 | （1）将上面的`[XXX]`改成当前库，共有三处。 151 | 152 | （2）上面的部署`token`，只有公开库才能拿到，免费账户的私有库不能获取这个 token。 153 | 154 | 如果`JamesIves/github-pages-deploy-action`使用 3.7.1 的老版，原始设置如下。 155 | 156 | ```yaml 157 | - name: Deploy to website 158 | uses: JamesIves/github-pages-deploy-action@3.7.1 159 | with: 160 | GIT_CONFIG_NAME: wangdoc-bot 161 | GIT_CONFIG_EMAIL: yifeng.ruan@gmail.com 162 | REPOSITORY_NAME: wangdoc/website 163 | ACCESS_TOKEN: ${{ secrets.WANGDOC_BOT_TOKEN }} 164 | BASE_BRANCH: master 165 | BRANCH: master # The branch the action should deploy to. 166 | FOLDER: dist # The folder the action should deploy. 167 | TARGET_FOLDER: dist/[xxx] 168 | CLEAN: true # Automatically remove deleted files from the deploy branch 169 | COMMIT_MESSAGE: update from [xxx] tutorial 170 | ``` 171 | 172 | ## Travis-CI 构建 173 | 174 | 注意，如果使用 GitHub Actions，则不需要设置 Travis-CI。 175 | 176 | 第一步，到 [Travis CI 的官网](https://travis-ci.com/organizations/wangdoc/repositories)，关联该仓库，开启自动构建。 177 | 178 | 注意，要到设置里面，把 Pull Request 触发自动构建的选项关掉。 179 | 180 | 第二步，在项目根目录下，新建`.travis.yml`，写入以下内容。 181 | 182 | ```yml 183 | language: node_js 184 | node_js: 185 | - 'node' 186 | 187 | branches: 188 | only: 189 | - master 190 | 191 | install: 192 | - npm ci 193 | # keep the npm cache around to speed up installs 194 | cache: 195 | directories: 196 | - "$HOME/.npm" 197 | 198 | script: bash ./deploy.sh 199 | env: 200 | global: 201 | - ENCRYPTION_LABEL: [xxxxxx] 202 | - COMMIT_AUTHOR_EMAIL: yifeng.ruan@gmail.com 203 | ``` 204 | 205 | 注意，上面代码中的`[xxxxxx]`要等到第四步进行替换。 206 | 207 | 第三步，项目根目录下，新建`deploy.sh`，写入以下内容。 208 | 209 | ```bash 210 | #!/bin/bash 211 | set -e # Exit with nonzero exit code if anything fails 212 | 213 | # Get the deploy key by using Travis's stored variables to decrypt deploy_key.enc 214 | ENCRYPTED_KEY_VAR="encrypted_${ENCRYPTION_LABEL}_key" 215 | ENCRYPTED_IV_VAR="encrypted_${ENCRYPTION_LABEL}_iv" 216 | ENCRYPTED_KEY=${!ENCRYPTED_KEY_VAR} 217 | ENCRYPTED_IV=${!ENCRYPTED_IV_VAR} 218 | openssl aes-256-cbc -K $ENCRYPTED_KEY -iv $ENCRYPTED_IV -in wangdoc-deploy-rsa.enc -out wangdoc-deploy-rsa -d 219 | chmod 600 wangdoc-deploy-rsa 220 | eval `ssh-agent -s` 221 | ssh-add wangdoc-deploy-rsa 222 | 223 | # Now that we're all set up, we can push. 224 | # git push $SSH_REPO $TARGET_BRANCH 225 | npm run build-and-commit 226 | ``` 227 | 228 | 第四步（待验证，可以跳过这步，直接执行下一个命令），在项目根目录下，添加私钥`wangdoc-deploy-rsa`。 229 | 230 | ```bash 231 | $ cp ~/.ssh/wangdoc-deploy-rsa . 232 | ``` 233 | 234 | 然后，使用`travis`命令加密`wangdoc-deploy-rsa`。如果没有安装 travis ci 的命令行客户端，可以参考官方的[安装文档](https://github.com/travis-ci/travis.rb#installation)`sudo gem install travis`。 235 | 236 | ```bash 237 | $ travis encrypt-file ~/.ssh/wangdoc-deploy-rsa 238 | ``` 239 | 240 | 屏幕上会显示加密编号，将这个编号写入`.travis.yml`。可以参考这个[范例文件](https://github.com/wangdoc/javascript-tutorial/blob/master/.travis.yml)。 241 | 242 | 第五步，重要！此时一定要删掉私钥`wangdoc-deploy-rsa`，只留下`wangdoc-deploy-rsa.enc`。 243 | 244 | ```bash 245 | $ rm wangdoc-deploy-rsa 246 | ``` 247 | 248 | ## loppo.yml 249 | 250 | 在 loppo.yml 里面加入文档仓库所在的分支。 251 | 252 | ```yaml 253 | branch: main 254 | ``` 255 | 256 | 如果不加 branch 字段，默认值为`master`。 257 | 258 | ## Disqus 讨论区 259 | 260 | 第一步，到 Disqus 新建讨论区，讨论区的 slug （shortname）为`wangdoc-[id]`（需要点击链接“customize your url”）。 261 | 262 | 第二步，设好 Disqus 以后，在`loppo.yml`里面设定如下设置。 263 | 264 | ```yaml 265 | hasComments: true|false 266 | isTutorial: true|false 267 | ``` 268 | 269 | --------------------------------------------------------------------------------