diff --git a/README.md b/README.md index 7385ee63b6..c29123aa6e 100644 --- a/README.md +++ b/README.md @@ -3,3 +3,15 @@ # VuePress > Minimalistic docs generator with Vue component based layout system + +## Why + +- **Writing First**: minimal setup, all you need is a markdown file. + +- **Vue-powered**: Use custom Vue components inside markdown, and develop custom themes using Vue single file components. + +- **Great Dev Experience**: enjoy the same enjoyable development experience of a Vue app. Leverage the full power of webpack (hot-reload, pre-processors), generate SEO-friendly static HTML, and works as an SPA after initial page load. + +- **Optimized for Docs**: many [built-in markdown extensions](./markdown.md) and default theme features for writing great documentation. + +- **GitHub Friendly**: source markdown files can link to each other using relative links that ends in `.md` so they are also readable on GitHub, auto-generates page edit links if a repo is provided. diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index b2068c510c..c4b913929d 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -9,15 +9,40 @@ module.exports = { ['link', { rel: 'icon', href: `${base}logo.png` }] ], themeConfig: { + // sidebar config sidebar: [ - '/', + '/getting-started', '/markdown', '/assets', '/using-vue', '/config', '/default-theme', '/theming', - '/deploy' - ] + '/deploy', + // nesting + ['Nesting', [ + '/markdown', + '/assets' + ]] + ], + + // multi-category sidebar config + + // sidebar: { + // '*': [/* ... */], + // '/guide/': [/* ... */], + // '/tutorial/': [/* ... */], + // '/api/': [/* ... */] + // }, + + // navbar config + + // nav: [ + // { + // title: 'Guide', + // link: '/getting-started', + // }, + // // ... + // ] } } diff --git a/docs/README.md b/docs/README.md index 99a78a223d..0e080f7072 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,3 @@ ---- -navTitle: Getting Started ---- - # VuePress > Minimalistic docs generator with Vue component based layout system @@ -17,59 +13,3 @@ navTitle: Getting Started - **Optimized for Docs**: many [built-in markdown extensions](./markdown.md) and default theme features for writing great documentation. - **GitHub Friendly**: source markdown files can link to each other using relative links that ends in `.md` so they are also readable on GitHub, auto-generates page edit links if a repo is provided. - -## Quickstart - -``` bash -# install globally -npm install -g vuepress - -# create a markdown file -echo "# Hello VuePress!" > index.md - -# start writing -vuepress dev . - -# build -vuepress build . -``` - -## Inside an Existing Project - -``` bash -# install as a dependency -npm install -D vuepress - -# create a docs directory -mkdir docs -# create a markdown file -echo "# Hello VuePress!" > docs/index.md - -# start writing -npx vuepress dev docs -``` - -Or, add some scripts to `package.json`: - -``` json -{ - "scripts": { - "docs:dev": "vuepress dev docs", - "docs:build": "vuepress build docs" - } -} -``` - -Then you can start writing with: - -``` bash -npm run docs:dev -``` - -To generate static assets, run: - -``` bash -npm run docs:build -``` - -By default the built files will be in `.vuepress/dist`. The files can be deployed to any static file server. See [Deployment Guide](./deploy.md) for guides on deploying to popular services. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000000..54d1585862 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,57 @@ +# Getting Started + +## Quickstart + +``` bash +# install globally +npm install -g vuepress + +# create a markdown file +echo "# Hello VuePress!" > index.md + +# start writing +vuepress dev . + +# build +vuepress build . +``` + +## Inside an Existing Project + +``` bash +# install as a dependency +npm install -D vuepress + +# create a docs directory +mkdir docs +# create a markdown file +echo "# Hello VuePress!" > docs/index.md + +# start writing +npx vuepress dev docs +``` + +Or, add some scripts to `package.json`: + +``` json +{ + "scripts": { + "docs:dev": "vuepress dev docs", + "docs:build": "vuepress build docs" + } +} +``` + +Then you can start writing with: + +``` bash +npm run docs:dev +``` + +To generate static assets, run: + +``` bash +npm run docs:build +``` + +By default the built files will be in `.vuepress/dist`. The files can be deployed to any static file server. See [Deployment Guide](./deploy.md) for guides on deploying to popular services. diff --git a/lib/default-theme/Layout.vue b/lib/default-theme/Layout.vue index 1776121fa6..df34ba7dee 100644 --- a/lib/default-theme/Layout.vue +++ b/lib/default-theme/Layout.vue @@ -2,10 +2,20 @@
@@ -18,36 +28,16 @@ import nprogress from 'nprogress' import Index from './Index.vue' import Page from './Page.vue' - -function normalize (path) { - return path.replace(/\.(md|html)$/, '') -} - -function findIndex (order, page) { - const pagePath = normalize(page.path) - for (let i = 0; i < order.length; i++) { - if (normalize(order[i]) === pagePath) { - return i - } - } - return Infinity -} +import resolveSidebar from './resolveSidebar' export default { components: { Index, Page }, computed: { - sortedPages () { - const pages = this.$site.pages - const order = this.$site.themeConfig.sidebar - if (!order) { - return pages - } else { - return pages.slice().sort((a, b) => { - const aIndex = findIndex(order, a) - const bIndex = findIndex(order, b) - return aIndex - bIndex - }) - } + sidebarItems () { + return resolveSidebar( + this.$route, + this.$site + ) } }, mounted () { diff --git a/lib/default-theme/resolveSidebar.js b/lib/default-theme/resolveSidebar.js new file mode 100644 index 0000000000..429f5ca4ae --- /dev/null +++ b/lib/default-theme/resolveSidebar.js @@ -0,0 +1,53 @@ +export default function resolveSidebar (route, site) { + const { pages, themeConfig } = site + const sidebarConfig = themeConfig.sidebar + if (!sidebarConfig) { + return pages + } else { + const matchingConfig = Array.isArray(sidebarConfig) + ? sidebarConfig + : resolveMatchingSidebar(route, sidebarConfig) + return matchingConfig.map(item => resolveItem(item, site.pages)) + } +} + +function resolveMatchingSidebar (route, sidebarConfig) { + for (const base in sidebarConfig) { + if (ensureEndingSlash(route.path).indexOf(base) === 0) { + return sidebarConfig[base] + } + } +} + +function ensureEndingSlash (path) { + return /(\.html|\/)$/.test(path) + ? path + : path + '/' +} + +function resolveItem (item, pages) { + if (typeof item === 'string') { + return Object.assign({ type: 'page' }, findPage(pages, item)) + } else if (Array.isArray(item)) { + return { + type: 'heading', + title: item[0], + children: (item[1] || []).map(child => resolveItem(child, pages)) + } + } else { + throw new Error(`Invalid sidebar item config: ${item}`) + } +} + +function findPage (pages, path) { + path = normalize(path) + for (let i = 0; i < pages.length; i++) { + if (normalize(pages[i].path) === path) { + return pages[i] + } + } +} + +function normalize (path) { + return path.replace(/\.(md|html)$/, '') +} diff --git a/lib/default-theme/theme.stylus b/lib/default-theme/theme.stylus index ca3cf6c489..f470f5167a 100644 --- a/lib/default-theme/theme.stylus +++ b/lib/default-theme/theme.stylus @@ -31,13 +31,13 @@ body padding-left 1.25em &:hover color darken(#41b883, 5%) - &.router-link-exact-active + &.router-link-active font-weight 600 color darken(#41b883, 5%) border-left-color darken(#41b883, 5%) .markdown - max-width 720px + max-width 760px margin 2em auto padding 0 2em @@ -151,7 +151,7 @@ p border 1px solid #ddd border-radius 4px -@media (max-width: 879px) +@media (max-width: 959px) body font-size 15px .sidebar @@ -163,7 +163,7 @@ p margin 1.5em 0 padding 0 1.5em -@media (max-width: 639px) +@media (max-width: 719px) body font-size 15px .sidebar