From 36daecddc08f5e4d3eb80e8b9c60b3087d097206 Mon Sep 17 00:00:00 2001 From: Evan You Date: Thu, 12 Apr 2018 18:27:52 -0400 Subject: [PATCH] refactor stylus --- docs/default-theme-config/README.md | 26 +++++++++---- docs/guide/README.md | 39 ++++++++++++++++--- docs/guide/getting-started.md | 15 ++++++- lib/default-theme/Home.vue | 2 +- lib/default-theme/Layout.vue | 2 +- lib/default-theme/NavLinks.vue | 2 +- lib/default-theme/Navbar.vue | 2 +- lib/default-theme/Page.vue | 2 +- lib/default-theme/SearchBox.vue | 2 +- lib/default-theme/Sidebar.vue | 4 +- lib/default-theme/SidebarButton.vue | 2 +- lib/default-theme/SidebarLink.vue | 2 +- .../styles/{arrow.stylus => arrow.styl} | 2 +- .../styles/{code.stylus => code.styl} | 2 +- .../styles/{config.stylus => config.styl} | 4 +- ...ustom-blocks.stylus => custom-blocks.styl} | 0 .../styles/{mobile.stylus => mobile.styl} | 2 +- .../{nprogress.stylus => nprogress.styl} | 0 .../styles/{theme.stylus => theme.styl} | 12 +++--- lib/prepare.js | 7 ++-- 20 files changed, 91 insertions(+), 38 deletions(-) rename lib/default-theme/styles/{arrow.stylus => arrow.styl} (95%) rename lib/default-theme/styles/{code.stylus => code.styl} (98%) rename lib/default-theme/styles/{config.stylus => config.styl} (73%) rename lib/default-theme/styles/{custom-blocks.stylus => custom-blocks.styl} (100%) rename lib/default-theme/styles/{mobile.stylus => mobile.styl} (96%) rename lib/default-theme/styles/{nprogress.stylus => nprogress.styl} (100%) rename lib/default-theme/styles/{theme.stylus => theme.styl} (94%) diff --git a/docs/default-theme-config/README.md b/docs/default-theme-config/README.md index c14cc039..c54c072f 100644 --- a/docs/default-theme-config/README.md +++ b/docs/default-theme-config/README.md @@ -1,21 +1,31 @@ # Default Theme Config -## Accent Color +## Simple CSS Override -## Logo +If you wish to apply simple overrides to the styling of the default theme, you can create an `.vuepress/override.styl` file. This is a [Stylus](http://stylus-lang.com/) file but you can use normal CSS syntax as well. -## Navbar +There are a few color variables you can tweak: -### nav +``` stylus +// showing default values +$accentColor = #3eaf7c +$textColor = #2c3e50 +$borderColor = #eaecef +$codeBgColor = #282c34 +``` + +## Options Reference -## Sidebar +### logo + +### nav ### sidebar ### sidebarDepth -## GitHub Repo & Edit Links +### editLinks -## Search +### docsDir -## Simple CSS Override +### docsBranch diff --git a/docs/guide/README.md b/docs/guide/README.md index c75224b6..59527976 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -4,20 +4,49 @@ next: ./getting-started # Introduction +VuePress is composed of two parts: a minimalistic static site generator with a Vue-powered theming system, and a default theme optimized for writing technical documentation. In fact, it was created to support the documentation needs of Vue's own sub projects. + +A VuePress site is in fact a Single-Page Application (SPA) powered by [Vue](http://vuejs.org/), [Vue Router](https://github.com/vuejs/vue-router) and [webpack](http://webpack.js.org/). If you've used Vue before, you will notice the familiar development experience when you are writing or developing custom themes (you can even use Vue DevTools to debug your custom theme!). + +When deployed, each page has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly. Once the page is loaded, Vue takes over the static content and turns it into a full SPA. Additional pages are fetched on demand as the user navigates around the site. + ## How It Works -## Todo Features +During the build, we create a server-rendered version of the app and render the corresponding HTML by virtually visiting each route. This approach is inspired by [Nuxt](https://nuxtjs.org/)'s `nuxt generate` command and other projects like [Gatsby](https://www.gatsbyjs.org/). + +Each markdown file is compiled into HTML with [markdown-it](https://github.com/markdown-it/markdown-it) and then processed as the template of a Vue component. This allows you to directly use Vue inside your markdown files and is great when you need to embed dynamic content. -### PWA Support +## Features -### Dropdown Items in Navbar +- [Built-in markdown extensions](./markdown.md) optimized for technical documentation +- [Ability to leverage Vue inside markdown files](./using-vue.md) +- [Vue-powered custom theme system](./custom-thems) +- A default theme with: + - Responsive layout + - Simple out-of-the-box header-based search + - Customizable navbar and sidebar + - Auto-generated GitHub link and page edit links -### Algolia DocSearch Integration +## Todo Features + +VuePress is still a work in progress. There are a few things that it currently does not support but are planned: + +- PWA Support +- Blogging support +- Dropdown Items in Navbar +- Google Analytics Integration +- Algolia DocSearch Integration ## Why Not ...? -### Nuxt / NuxtDoc +### Nuxt + +Nuxt is capable of doing what VuePress does, but it is designed for building applications. VuePress is focused on content-centric static sites and provides features tailored for technical documentation out of the box. ### Docsify / Docute +Both are great projects and also Vue-powered. Except they are both completely runtime-driven and thus not SEO-friendly. If you don't care about SEO and don't want to mess with installing dependencies, these are still great choices. + ### Hexo + +Hexo is great - in fact, we are probably still a long way to go from migrating away from it for our main site. The biggest problem is that its theming system is very static and string-based - we really want to leverage Vue for both the layout and the interactivity. Also, Hexo's markdown rendering isn't the most flexible to configure. diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index b91f1583..9c272825 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -6,6 +6,8 @@ next: ./markdown ## Global Installation +If you just want to play around with VuePress, you can install it globally: + ``` bash # install globally npm install -g vuepress @@ -22,6 +24,8 @@ vuepress build . ## Inside an Existing Project +If you have an existing project and would like to keep documentation inside the project, you should install VuePress as a local dependency. This setup also allows you to use CI or services like Netlify for automatic deployment on push. + ``` bash # install as a local dependency npm install -D vuepress @@ -62,9 +66,16 @@ By default the built files will be in `.vuepress/dist`, which can be configured ## Basic Configurations -### Title and Description +Right now our page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let's first create a `.vuepress` directory inside your docs directory. This is where all VuePress-specific files will be placed in. + +The essential file for configuring a VuePress site is `.vuepress/config.js`, which simply exports a JavaScript object: -### Logo +``` js +module.exports = { + title: 'Hello VuePress', + description: 'Just playing around' +} +``` ### Navbar Links diff --git a/lib/default-theme/Home.vue b/lib/default-theme/Home.vue index 694397cb..3d31be33 100644 --- a/lib/default-theme/Home.vue +++ b/lib/default-theme/Home.vue @@ -41,7 +41,7 @@ export default { - + diff --git a/lib/default-theme/NavLinks.vue b/lib/default-theme/NavLinks.vue index f117d36c..71cc8731 100644 --- a/lib/default-theme/NavLinks.vue +++ b/lib/default-theme/NavLinks.vue @@ -46,7 +46,7 @@ export default {