diff --git a/bin/vitepress.js b/bin/vitepress.js index fe81330ffdd9..a5b135ebb71b 100755 --- a/bin/vitepress.js +++ b/bin/vitepress.js @@ -31,6 +31,13 @@ if (!command || command === 'dev') { console.error(chalk.red(`build error:\n`), err) process.exit(1) }) +} else if (command === 'serve') { + require('../dist/node') + .serve(argv) + .catch((err) => { + console.error(chalk.red(`failed to start server. error:\n`), err) + process.exit(1) + }) } else { console.log(chalk.red(`unknown command "${command}".`)) process.exit(1) diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 3a3c70951b51..350f0e0d87bd 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -25,7 +25,8 @@ module.exports = { { text: 'What is VitePress?', link: '/' }, { text: 'Getting Started', link: '/guide/getting-started' }, { text: 'Configuration', link: '/guide/configuration' }, - { text: 'Customization', link: '/guide/customization' } + { text: 'Customization', link: '/guide/customization' }, + { text: 'Deploying', link: '/guide/deploy' } ] } ], diff --git a/docs/guide/deploy.md b/docs/guide/deploy.md new file mode 100644 index 000000000000..6977ffe6b06a --- /dev/null +++ b/docs/guide/deploy.md @@ -0,0 +1,49 @@ +# Deploying + +The following guides are based on some shared assumptions: + +- You are placing your docs inside the `docs` directory of your project; +- You are using the default build output location (`.vitepress/dist`); +- VuePress is installed as a local dependency in your project, and you have setup the following npm scripts: + +```json +{ + "scripts": { + "docs:build": "vuepress build docs", + "docs:serve": "vuepress serve docs" + } +} +``` + +## Building The Docs + +You may run `yarn docs:build` command to build the docs. + +```bash +$ yarn docs:build +``` + +By default, the build output will be placed at `.vitepress/dist`. You may deploy this `dist` folder to any of your preferred platforms. + +### Testing The Docs Locally + +Once you've built the docs, you may test them locally by running `yarn docs:serve` command. + +```bash +$ yarn docs:build +$ yarn docs:serve +``` + +The `serve` command will boot up local static web server that serves the files from `.vitepress/dist` at http://localhost:3000. It's an easy way to check if the production build looks OK in your local environment. + +You may configure the port of the server py passing `--port` flag as an argument. + +```json +{ + "scripts": { + "docs:serve": "vuepress serve docs --port 8080" + } +} +``` + +Now the `docs:serve` method will launch the server at http://localhost:8080. diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index ea9603378d98..1bc4a3e7ea32 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -32,7 +32,8 @@ This section will help you build a basic VuePress documentation site from ground { "scripts": { "docs:dev": "vitepress dev docs", - "docs:build": "vitepress build docs" + "docs:build": "vitepress build docs", + "docs:serve": "vitepress serve docs" } } ``` @@ -44,3 +45,7 @@ This section will help you build a basic VuePress documentation site from ground ``` VitePress will start a hot-reloading development server at http://localhost:3000. + +By now, you should have a basic but functional VuePress documentation site. + +When your documentation site starts to take shape, be sure to read the [deployment guide](./deploy). diff --git a/package.json b/package.json index 5aec8a64f8c9..1a3f83713bf9 100644 --- a/package.json +++ b/package.json @@ -22,13 +22,14 @@ "dev-watch": "node scripts/watchAndCopy", "build": "rimraf -rf dist && node scripts/copyShared && tsc -p src/client && tsc -p src/node && node scripts/copyClient", "lint": "yarn lint:js && yarn lint:ts", - "lint:js": "prettier --check --write \"{bin,scripts,src}/**/*.js\"", - "lint:ts": "prettier --check --write --parser typescript \"{src,types}/**/*.ts\"", + "lint:js": "prettier --check --write \"{bin,docs,scripts,src}/**/*.js\"", + "lint:ts": "prettier --check --write --parser typescript \"{src,docs,types}/**/*.ts\"", "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s", "release": "bash scripts/release.sh", "docs": "run-p dev docs-dev", "docs-dev": "node ./bin/vitepress dev docs", - "docs-build": "yarn build && node ./bin/vitepress build docs" + "docs-build": "yarn build && node ./bin/vitepress build docs", + "docs-serve": "yarn docs-build && node ./bin/vitepress serve --root docs" }, "engines": { "node": ">=10.0.0" @@ -85,12 +86,16 @@ }, "devDependencies": { "@types/fs-extra": "^9.0.1", + "@types/koa": "^2.11.6", + "@types/koa-static": "^4.0.1", "@types/lru-cache": "^5.1.0", "@types/markdown-it": "^10.0.2", "@types/node": "^13.13.4", "@types/postcss-load-config": "^2.0.1", "chokidar": "^3.4.2", "conventional-changelog-cli": "^2.1.0", + "koa": "^2.13.0", + "koa-static": "^5.0.0", "lint-staged": "^10.3.0", "npm-run-all": "^4.1.5", "prettier": "^2.0.5", diff --git a/src/node/index.ts b/src/node/index.ts index 93c4dfa744fa..0a0d956b1fca 100644 --- a/src/node/index.ts +++ b/src/node/index.ts @@ -1,3 +1,4 @@ export * from './server' export * from './build/build' +export * from './serve/serve' export * from './config' diff --git a/src/node/serve/serve.ts b/src/node/serve/serve.ts new file mode 100644 index 000000000000..b51e169feb4e --- /dev/null +++ b/src/node/serve/serve.ts @@ -0,0 +1,21 @@ +import Koa from 'koa' +import koaServe from 'koa-static' +import { resolveConfig } from '../config' + +export interface ServeOptions { + root?: string + port?: number +} + +export async function serve(options: ServeOptions = {}) { + const port = options.port !== undefined ? options.port : 3000 + const site = await resolveConfig(options.root) + + const app = new Koa() + + app.use(koaServe(site.outDir)) + + app.listen(port) + + console.log(`listening at http://localhost:${port}`) +} diff --git a/yarn.lock b/yarn.lock index 26155a768480..d1c6519acb89 100644 --- a/yarn.lock +++ b/yarn.lock @@ -209,7 +209,22 @@ dependencies: "@types/koa" "*" -"@types/koa@*", "@types/koa@^2.11.4": +"@types/koa-send@*": + version "4.1.2" + resolved "https://registry.yarnpkg.com/@types/koa-send/-/koa-send-4.1.2.tgz#978f8267ad116d12ac6a18fecd8f34c5657e09ad" + integrity sha512-rfqKIv9bFds39Jxvsp8o3YJLnEQVPVriYA14AuO2OY65IHh/4UX4U/iMs5L0wATpcRmm1bbe0BNk23TRwx3VQQ== + dependencies: + "@types/koa" "*" + +"@types/koa-static@^4.0.1": + version "4.0.1" + resolved "https://registry.yarnpkg.com/@types/koa-static/-/koa-static-4.0.1.tgz#b740d80a549b0a0a7a3b38918daecde88a7a50ec" + integrity sha512-SSpct5fEcAeRkBHa3RiwCIRfDHcD1cZRhwRF///ZfvRt8KhoqRrhK6wpDlYPk/vWHVFE9hPGqh68bhzsHkir4w== + dependencies: + "@types/koa" "*" + "@types/koa-send" "*" + +"@types/koa@*", "@types/koa@^2.11.4", "@types/koa@^2.11.6": version "2.11.6" resolved "https://registry.yarnpkg.com/@types/koa/-/koa-2.11.6.tgz#b7030caa6b44af801c2aea13ba77d74aff7484d5" integrity sha512-BhyrMj06eQkk04C97fovEDQMpLpd2IxCB4ecitaXwOKGq78Wi2tooaDOWOFGajPk8IkQOAtMppApgSVkYe1F/A==