diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 289ec07cbe..4c223bfdf5 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -19,6 +19,8 @@ about: Create a report to help us improve + + #### What is expected? #### What is actually happening? diff --git a/.gitignore b/.gitignore index 96930bdd73..c090307948 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ node_modules .temp vuepress TODOs.md +.idea diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b821cdfc6..e6ef90e4b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,18 +1,95 @@ + +## [0.14.1](https://github.com/vuejs/vuepress/compare/v0.14.0...v0.14.1) (2018-08-09) + + +### Bug Fixes + +* **$default-theme:** default search box line wrap ([03c812b](https://github.com/vuejs/vuepress/commit/03c812b)) +* **$default-theme:** navbar's regression - siteName null check ([02a4713](https://github.com/vuejs/vuepress/commit/02a4713)) + + + + +# [0.14.0](https://github.com/vuejs/vuepress/compare/v0.13.1...v0.14.0) (2018-08-08) + + +### Bug Fixes + +* **$default-theme:** algolia search doesn't work well at i18n mode ([e8a6ab1](https://github.com/vuejs/vuepress/commit/e8a6ab1)) +* **$default-theme:** navbar's messy layout at narrow screen ([#714](https://github.com/vuejs/vuepress/issues/714)) ([3e1da57](https://github.com/vuejs/vuepress/commit/3e1da57)) +* **$default-theme:** set alias "collapsible" to "collapsable" (close: [#705](https://github.com/vuejs/vuepress/issues/705)) ([#706](https://github.com/vuejs/vuepress/issues/706)) ([ad66fa8](https://github.com/vuejs/vuepress/commit/ad66fa8)) +* **$build:** skip format data.head if not exist while loading toml config ([#707](https://github.com/vuejs/vuepress/issues/707)) ([bb48a77](https://github.com/vuejs/vuepress/commit/bb48a77)) + + +### Features + +* **core:** support writing HTML(Vue) anywhere in the header. ([#711](https://github.com/vuejs/vuepress/issues/711)) ([885496e](https://github.com/vuejs/vuepress/commit/885496e)) +* **$webpack:** display host url at dev HMR log ([2e8d69c](https://github.com/vuejs/vuepress/commit/2e8d69c)) + + + + +## [0.13.1](https://github.com/vuejs/vuepress/compare/v0.13.0...v0.13.1) (2018-08-01) + + +### Bug Fixes + +* **core:** normalize override file path in windows ([#692](https://github.com/vuejs/vuepress/issues/692)) (close: [#642](https://github.com/vuejs/vuepress/issues/642)) ([9537c2c](https://github.com/vuejs/vuepress/commit/9537c2c)) +* **$default-theme:** `py` lang label doesn't display in code block ([#690](https://github.com/vuejs/vuepress/issues/690)) ([88b65cc](https://github.com/vuejs/vuepress/commit/88b65cc)) + + + + +# [0.13.0](https://github.com/vuejs/vuepress/compare/v0.12.0...v0.13.0) (2018-07-28) + + +### Bug Fixes + +* **$seo:** Avoid duplicate `description meta` at runtime. (close: [#665](https://github.com/vuejs/vuepress/issues/665)) ([b207a5f](https://github.com/vuejs/vuepress/commit/b207a5f)) +* **$default-theme:** Scoped styles of `Badge` component (close: [#653](https://github.com/vuejs/vuepress/issues/653)) ([#657](https://github.com/vuejs/vuepress/issues/657)) ([9b602f2](https://github.com/vuejs/vuepress/commit/9b602f2)) +* **$build:** set `babelrc: false` in babel-loader options ([#644](https://github.com/vuejs/vuepress/issues/644)) ([c500201](https://github.com/vuejs/vuepress/commit/c500201)) ([@posva](https://github.com/posva)) +* **$build:** exclude dest folder from pageFiles (close: [#654](https://github.com/vuejs/vuepress/issues/654)) ([#655](https://github.com/vuejs/vuepress/issues/655)) ([c1fe692](https://github.com/vuejs/vuepress/commit/c1fe692)) +* **$build:** markdown config should be included in `cache-loader` identifier ([0ad1a45](https://github.com/vuejs/vuepress/commit/0ad1a45)) +* **$markdown:** cannot highlight external python file (`.py`) correctly (close: [#660](https://github.com/vuejs/vuepress/issues/660)) ([2a33075](https://github.com/vuejs/vuepress/commit/2a33075)) +* **$markdown:** missing space between `italics` and `bold` (close: [#661](https://github.com/vuejs/vuepress/issues/661)) ([7730ee1](https://github.com/vuejs/vuepress/commit/7730ee1)) + 1. `markdown-it` compiler will intendedly reserve this space between some inline elements, but `preserveWhitespace: false` will remove them. (Ref: [vue-template-compiler#options](https://github.com/vuejs/vue/tree/dev/packages/vue-template-compiler#options)) + 2. **Performance Impact**: Size of whole assets of vuepress documentation: + - Before (1952 kb) + - After (1960 kb) + +### Features + +* **$cli:** debug flag at dev mode ([231da6a](https://github.com/vuejs/vuepress/commit/231da6a)) +* **$default-theme:** transform `Badge` into async component ([de9a51b](https://github.com/vuejs/vuepress/commit/de9a51b)) +* **$default-theme**(**$pwa**): `themeConfig.serviceWorker.updatePopup` option (close: [#453](https://github.com/vuejs/vuepress/issues/453)) ([#533](https://github.com/vuejs/vuepress/issues/533)) ([14dbd1e](https://github.com/vuejs/vuepress/commit/14dbd1e)) ([@mysticatea](https://github.com/mysticatea)) + ``` js + module.exports = { + themeConfig: { + serviceWorker: { + updatePopup: true + } + } + } + ``` + + + # [0.12.0](https://github.com/vuejs/vuepress/compare/v0.11.0...v0.12.0) (2018-07-12) ### Bug Fixes -* npm audit vulnerability (close: [#493](https://github.com/vuejs/vuepress/issues/493))([#641](https://github.com/vuejs/vuepress/issues/641)) ([8dde5d8](https://github.com/vuejs/vuepress/commit/8dde5d8)) -* wrong sidebar slugs and anchor link at content (close: [#645](https://github.com/vuejs/vuepress/issues/645)) ([c2eaff3](https://github.com/vuejs/vuepress/commit/c2eaff3)) +* **$build** npm audit vulnerability (close: [#493](https://github.com/vuejs/vuepress/issues/493))([#641](https://github.com/vuejs/vuepress/issues/641)) ([8dde5d8](https://github.com/vuejs/vuepress/commit/8dde5d8)) +* **$markdown**: wrong sidebar slugs and anchor link at content (close: [#645](https://github.com/vuejs/vuepress/issues/645)) ([c2eaff3](https://github.com/vuejs/vuepress/commit/c2eaff3)) ### Features -* version data layer ([0c5b752](https://github.com/vuejs/vuepress/commit/0c5b752)) -* **$default-theme:** new file-level API: style.styl. ([2f53f2f](https://github.com/vuejs/vuepress/commit/2f53f2f)) - +* **$core:**: version data layer ([0c5b752](https://github.com/vuejs/vuepress/commit/0c5b752)) +* **$default-theme:** new file-level API: `style.styl`. ([2f53f2f](https://github.com/vuejs/vuepress/commit/2f53f2f)) + 1. Fixed overriding css variable doesn't work at `0.11.0` (close: [#639](https://github.com/vuejs/vuepress/issues/639)) + 2. Split `override.styl` into two APIs: `override.styl` and `style.styl`, the former will focus on ONLY the stylus constants override, while the latter will focus on styles override or custom styles. See also: https://vuepress.vuejs.org/default-theme-config/#simple-css-override. diff --git a/LICENSE b/LICENSE index 15f1f7e7a4..2f244ac814 100644 --- a/LICENSE +++ b/LICENSE @@ -1,21 +1,395 @@ -The MIT License (MIT) - -Copyright (c) 2018-present, Yuxi (Evan) You - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. +Attribution 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More_considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/README-cn.md b/README-cn.md new file mode 100644 index 0000000000..31c580ac95 --- /dev/null +++ b/README-cn.md @@ -0,0 +1,48 @@ +

+ + logo + +

+ +# VuePress + +> Minimalistic docs generator with Vue component based layout system + +https://vuepress.vuejs.org/ + +## Features + +- [Built-in markdown extensions](https://vuepress.vuejs.org/guide/markdown.html) optimized for technical documentation +- [Ability to leverage Vue inside markdown files](https://vuepress.vuejs.org/guide/using-vue.html) +- [Vue-powered custom theme system](https://vuepress.vuejs.org/guide/custom-themes.html) +- Service Worker Integration +- Google Analytics Integration +- A default theme with: + - Responsive layout + - Optional Homepage + - Automatic basic typeahead search + - Customizable navbar and sidebar + - Auto-generated GitHub link and page edit links + +## Todo Features + +VuePress is still a work in progress. There are a few things that it currently does not support but are planned: + +- Multi-Language Support +- Algolia DocSearch Integration +- Blogging support + +Contributions are welcome! + +## Development + +> Please make sure your version of Node.js is greater than 8. + +``` bash +yarn +yarn dev # serves VuePress' own docs with itself +``` + +## License + +MIT diff --git a/README-en.md b/README-en.md new file mode 100644 index 0000000000..5a440123ab --- /dev/null +++ b/README-en.md @@ -0,0 +1,47 @@ +

+ + logo + +

+ +# VuePress + +> Minimalistic docs generator with Vue component based layout system + +https://vuepress.vuejs.org/ + +## Features + +- [Built-in markdown extensions](https://vuepress.vuejs.org/guide/markdown.html) optimized for technical documentation +- [Ability to leverage Vue inside markdown files](https://vuepress.vuejs.org/guide/using-vue.html) +- [Vue-powered custom theme system](https://vuepress.vuejs.org/guide/custom-themes.html) +- Service Worker Integration +- Google Analytics Integration +- Multi-Language Support +- A default theme with: + - Responsive layout + - Optional Homepage + - Automatic basic typeahead search + - Customizable navbar and sidebar + - Auto-generated GitHub link and page edit links + +## Todo Features + +VuePress is still a work in progress. There are a few things that it currently does not support but are planned: + +- Blogging support + +Contributions are welcome! + +## Development + +> Please make sure your version of Node.js is greater than 8. + +``` bash +yarn +yarn dev # serves VuePress' own docs with itself +``` + +## License + +MIT diff --git a/README.md b/README.md index b53d7962b8..e3245e5211 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

- - logo + + logo

@@ -12,85 +12,17 @@ # VuePress -> Minimalistic docs generator with Vue component based layout system +

主要链接

-https://vuepress.vuejs.org/ +* 首页链接：https://docschina.org +* git 仓库：https://github.com/docschina +* 群聊：https://docschina.org/talk +* 团队：https://docschina.org/team +* gitter：https://gitter.im/docschina +* slack：https://docschina.slack.com/ -## Features +

授权方式

-**Built-in markdown extensions** - -* [Table of Contents](https://vuepress.vuejs.org/guide/markdown.html#table-of-contents) -* [Custom Containers](https://vuepress.vuejs.org/guide/markdown.html#custom-containers) -* [Line Highlighting](https://vuepress.vuejs.org/guide/markdown.html#line-highlighting-in-code-blocks) -* [Line Numbers](https://vuepress.vuejs.org/guide/markdown.html#line-numbers) -* [Import Code Snippets](https://vuepress.vuejs.org/guide/markdown.html#import-code-snippets) - -**Using Vue in Markdown** - -* [Templating](https://vuepress.vuejs.org/guide/using-vue.html#templating) -* [Using Components](https://vuepress.vuejs.org/guide/using-vue.html#using-components) - -**Vue-powered custom theme system** - -* [Metadata](https://vuepress.vuejs.org/guide/custom-themes.html#site-and-page-metadata) -* [Content Excerpt](https://vuepress.vuejs.org/guide/custom-themes.html#content-excerpt) - -**Default theme** - -* Responsive layout -* [Optional Homepage](https://vuepress.vuejs.org/default-theme-config/#homepage) -* [Simple out-of-the-box header-based search](https://vuepress.vuejs.org/default-theme-config/#built-in-search) -* [Algolia Search](https://vuepress.vuejs.org/default-theme-config/#algolia-search) -* Customizable [navbar](https://vuepress.vuejs.org/default-theme-config/#navbar) and [sidebar](https://vuepress.vuejs.org/default-theme-config/#sidebar) -* [Auto-generated GitHub link and page edit links](https://vuepress.vuejs.org/default-theme-config/#git-repo-and-edit-links) - -**Miscellaneous** - -* [Multi-Language Support](https://vuepress.vuejs.org/guide/i18n.html) -* [Service Worker](https://vuepress.vuejs.org/config/#serviceworker) -* [Google Analytics](https://vuepress.vuejs.org/config/#ga) -* [Last Updated](https://vuepress.vuejs.org/default-theme-config/#last-updated) - -## Showcase - -Websites built with VuePress: - -**Vue Ecosystem** - -* [vue-cli](https://cli.vuejs.org/) -* [vuex](https://vuex.vuejs.org/) -* [vue-server-renderer](https://ssr.vuejs.org/) -* [vue-router](https://github.com/vuejs/vue-router) -* [vue-test-utils](https://vue-test-utils.vuejs.org/) -* [vue-loader](https://vue-loader.vuejs.org/) -* [vetur](https://vuejs.github.io/vetur/) -* [rollup-plugin-vue](https://rollup-plugin-vue.vuejs.org/) - -**Community** - -* [cr-vue](https://cr-vue.mio3io.com/) -* [vuesax](https://lusaxweb.github.io/vuesax/) - -## Todo Features - -VuePress is still a work in progress. There are a few things that it currently does not support but are planned: - -- Plugin support -- Blogging support - -Contributions are welcome! - -## Development - -> Please make sure your version of Node.js is greater than 8. - -``` bash -yarn -yarn dev # serves VuePress' own docs with itself -yarn test # make sure your code change pass the test -``` - -## License - -[MIT](https://github.com/vuejs/vuepress/blob/master/LICENSE) +- 印记中文所有的翻译文档，统一遵循 [“保留署名—非商用”创意共享 4.0 许可证（CC BY-NC 4.0）](https://creativecommons.org/licenses/by-nc/4.0/deed.zh) 授权方式。 +- 你不用知会我们就可以转载，但**必须保持署名为“印记中文”，以及链接到 https://docschina.org ，并且不得去掉本页入口链接，也不得修改文档内容），并且不得用于商业目的**。 +- 如果需要进行任何商业推广，请接洽 印记中文负责人李成熙(@lcxfs1991)（QQ: 249806703 && 邮箱：lcxfs1991@gmail.com），我们将给出积极的回应。 diff --git a/bin/vuepress.js b/bin/vuepress.js index 1f6c35da3e..36433168e6 100755 --- a/bin/vuepress.js +++ b/bin/vuepress.js @@ -27,8 +27,9 @@ program .description('start development server') .option('-p, --port ', 'use specified port (default: 8080)') .option('-h, --host ', 'use specified host (default: 0.0.0.0)') - .action((dir = '.', { host, port }) => { - wrapCommand(dev)(path.resolve(dir), { host, port }) + .option('--debug', 'start development server in debug mode') + .action((dir = '.', { host, port, debug }) => { + wrapCommand(dev)(path.resolve(dir), { host, port, debug }) }) program diff --git a/docs/.vuepress/components/Bit.vue b/docs/.vuepress/components/Bit.vue index 51d4048aba..433d362a9e 100644 --- a/docs/.vuepress/components/Bit.vue +++ b/docs/.vuepress/components/Bit.vue @@ -1,8 +1,8 @@ diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 9bdb719e0f..7a6866f63a 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -2,14 +2,9 @@ module.exports = { dest: 'vuepress', locales: { '/': { - lang: 'en-US', - title: 'VuePress', - description: 'Vue-powered Static Site Generator' - }, - '/zh/': { lang: 'zh-CN', title: 'VuePress', - description: 'Vue 驱动的静态网站生成器' + description: 'Vue 驱动的静态站点生成工具' } }, head: [ @@ -26,62 +21,31 @@ module.exports = { serviceWorker: true, theme: 'vue', themeConfig: { - repo: 'vuejs/vuepress', + repo: 'docschina/vuepress', editLinks: true, docsDir: 'docs', locales: { '/': { - label: 'English', - selectText: 'Languages', - editLinkText: 'Edit this page on GitHub', - lastUpdated: 'Last Updated', - nav: [ - { - text: 'Guide', - link: '/guide/', - }, - { - text: 'Config Reference', - link: '/config/' - }, - { - text: 'Default Theme Config', - link: '/default-theme-config/' - }, - { - text: 'Changelog', - link: 'https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md' - } - ], - sidebar: { - '/guide/': genSidebarConfig('Guide') - } - }, - '/zh/': { label: '简体中文', selectText: '选择语言', - editLinkText: '在 GitHub 上编辑此页', + editLinkText: '编辑此页', lastUpdated: '上次更新', nav: [ { text: '指南', - link: '/zh/guide/', - }, - { - text: '配置', - link: '/zh/config/' + link: '/guide/', }, { - text: '默认主题', - link: '/zh/default-theme-config/' + text: '配置参考', + link: '/config/' }, { - text: 'Changelog', - link: 'https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md' + text: '默认主题配置', + link: '/default-theme-config/' } ], sidebar: { - '/zh/guide/': genSidebarConfig('指南') + '/guide/': genSidebarConfig('指南') } } } diff --git a/docs/.vuepress/override.styl b/docs/.vuepress/override.styl deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/README.md b/docs/README.md index 3651cc3ba8..93987a3a21 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ --- home: true heroImage: /hero.png -actionText: Get Started → +actionText: 起步 → actionLink: /guide/ footer: MIT Licensed | Copyright © 2018-present Evan You --- @@ -12,35 +12,35 @@ footer: MIT Licensed | Copyright © 2018-present Evan You
-

Simplicity First

-

Minimal setup with markdown-centered project structure helps you focus on writing.

+

简明优先

+

对以 markdown 为中心的项目结构，做最简化的配置，帮助你专注于创作。

-

Vue-Powered

-

Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.

+

Vue 驱动

+

享用 Vue + webpack 开发环境，在 markdown 中使用 Vue 组件，并通过 Vue 开发自定义主题。

-

Performant

-

VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.

+

性能高效

+

VuePress 将每个页面生成为预渲染的静态 HTML，每个页面加载之后，然后作为单页面应用程序(SPA)运行。

-### As Easy as 1, 2, 3 +### 起步就像数 1, 2, 3 一样容易 ``` bash -# install -yarn global add vuepress # OR npm install -g vuepress +# 安装 +yarn global add vuepress # 或 npm install -g vuepress -# create a markdown file +# 创建一个 markdown 文件 echo '# Hello VuePress' > README.md -# start writing +# 开始编写 vuepress dev -# build to static files +# 构建为静态文件 vuepress build ``` -::: warning COMPATIBILITY NOTE -VuePress requires Node.js >= 8. +::: warning 兼容性注意事项 +VuePress 要求 Node.js >= 8。 ::: diff --git a/docs/config/README.md b/docs/config/README.md index 1899496557..13dd06ea83 100644 --- a/docs/config/README.md +++ b/docs/config/README.md @@ -2,46 +2,46 @@ sidebar: auto --- -# Config Reference +# 配置参考 -## Basic Config +## 基本配置(basic config) ### base - Type: `string` - Default: `/` -The base URL the site will be deployed at. You will need to set this if you plan to deploy your site under a sub path, for example GitHub pages. If you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `"/bar/"`. It should always start and end with a slash. +网站用来部署的基准 URL。如果你打算在子路径下部署你的站点，例如 GitHub 页面，则需要设置此项。如果你打算将你的网站部署到`https://foo.github.io/bar/`，则应将 `base` 设置为 `"/bar/"`。它应该始终以斜杠开始和结束。 -The `base` is automatically prepended to all the URLs that start with `/` in other options, so you only need to specify it once. +在其他选项中，`base` 会自动添加到以 `/` 开头的所有 URL 中，因此你只需指定一次即可。 -**Also see:** +**另请参考：** -- [Base URL](../guide/assets.md#base-url) -- [Deploy Guide > Github Pages](../guide/deploy.md#github-pages) +- [基准 URL](../guide/assets.md#相对-urls) +- [部署教程 > Github 页面](../guide/deploy.md#github-页面) ### title - Type: `string` - Default: `undefined` -Title for the site. This will be the prefix for all page titles, and displayed in the navbar in the default theme. +网站的标题。这将是所有页面标题的前缀，并显示在默认主题的导航栏中。 ### description - Type: `string` - Default: `undefined` -Description for the site. This will be rendered as a `` tag in the page HTML. +网站描述。这将在页面 HTML 中表现为一个 `` 标签。 ### head - Type: `Array` - Default: `[]` -Extra tags to be injected to the page HTML ``. Each tag can be specified in the form of `[tagName, { attrName: attrValue }, innerHTML?]`. For example, to add a custom favicon: +被注入页面 HTML `` 额外的标签。每个标签可以用 `[tagName, { attrName: attrValue }, innerHTML?]` 的形式指定。例如，要添加自定义图标： ``` js module.exports = { @@ -56,31 +56,31 @@ module.exports = { - Type: `string` - Default: `'0.0.0.0'` -Specify the host to use for the dev server. +指定用于 dev 服务器的主机。 ### port - Type: `number` - Default: `8080` -Specify the port to use for the dev server. +指定用于 dev 服务器的端口。 ### dest - Type: `string` - Default: `.vuepress/dist` -Specify the output directory for `vuepress build`. +指定 `vuepress build` 的输出目录。 ### ga - Type: `string` - Default: `undefined` -Provide the Google Analytics ID to enable integration. +提供 Google AnalyticsID 来开启集成功能。 -::: tip -Please be aware of [GDPR (2018 reform of EU data protection rules)](https://ec.europa.eu/commission/priorities/justice-and-fundamental-rights/data-protection/2018-reform-eu-data-protection-rules_en) and consider setting Google Analytics to [anonymize IPs](https://support.google.com/analytics/answer/2763052?hl=en) where appropriate and/or needed. +::: tip 提示 +请留意 [GDPR (2018年欧盟数据保护规则改革)](https://ec.europa.eu/commission/priorities/justice-and-fundamental-rights/data-protection/2018-reform-eu-data-protection-rules_en), 在合适或者需要的情况下，考虑将 Google Analytics 设置为[匿名化的 IP](https://support.google.com/analytics/answer/2763052?hl=zh-Hans)。 ::: ### serviceWorker @@ -88,9 +88,9 @@ Please be aware of [GDPR (2018 reform of EU data protection rules)](https://ec.e - Type: `boolean` - Default: `false` -If set to `true`, VuePress will automatically generate and register a service worker that caches the content for offline use (only enabled in production). +如果设置为 `true`，VuePress 将自动生成并注册一个 service worker ，这个 worker 将内容缓存以供离线使用（仅在生产环境中启用）。 -If developing a custom theme, the `Layout.vue` component will also be emitting the following events: +如果开发了一个自定义主题，`Layout.vue` 组件还将触发以下事件： - `sw-ready` - `sw-cached` @@ -98,10 +98,10 @@ If developing a custom theme, the `Layout.vue` component will also be emitting t - `sw-offline` - `sw-error` -::: tip PWA NOTES -The `serviceWorker` option only handles the service worker. To make your site fully PWA-compliant, you will need to provide the Web App Manifest and icons in `.vuepress/public`. For more details, see [MDN docs about the Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest). +::: tip PWA 注意事项 +`serviceWorker` 选项只能处理 service worker。要使你的站点完全符合 PWA，你需要在`.vuepress/public` 中提供 Web App 清单和图标。有关更多详细信息，请参阅 [MDN 关于 Web 应用程序清单的文档](https://developer.mozilla.org/en-US/docs/Web/Manifest)。 -Also, only enable this if you are able to deploy your site with SSL, since service worker can only be registered under HTTPs URLs. +此外，只有在你能够使用 SSL 部署你的站点时才能启用此功能，因为 service worker 只能在 HTTPs URLs 下注册。 ::: ### locales @@ -109,34 +109,34 @@ Also, only enable this if you are able to deploy your site with SSL, since servi - Type: `{ [path: string]: Object }` - Default: `undefined` -Specify locales for i18n support. For more details, see the guide on [Internationalization](../guide/i18n.md). +指定用于 i18n 支持，要获取更多细节，请参考[国际化指南](../guide/i18n.md)。 ### shouldPrefetch -- Type: `Function` -- Default: `() => true` +- 类型: `Function` +- 默认值: `() => true` -A function to control what files should have `` resource hints generated. See [shouldPrefetch](https://ssr.vuejs.org/api/#shouldprefetch). +一个函数，用来控制对于哪些文件，是需要生成 `` 资源提示的。请参考 [shouldPrefetch](https://ssr.vuejs.org/zh/api/#shouldpreload)。 -## Theming +## 主题化(theming) ### theme - Type: `string` - Default: `undefined` -Specify this to use a custom theme. With the value of `"foo"`, VuePress will attempt to load the theme component at `node_modules/vuepress-theme-foo/Layout.vue`. +指定此选项来使用自定义主题。使用 `"foo"` 的值，VuePress 将尝试在 `node_modules/vuepress-theme-foo/Layout.vue` 加载主题组件。 ### themeConfig - Type: `Object` - Default: `{}` -Provide config options to the used theme. The options will vary depending on the theme you are using. +为使用的主题提供配置选项。这些选项将根据你使用的主题而有所不同。 -**Also see:** +**另请参阅：** -- [Default Theme Configuration](../default-theme-config/README.md). +- [默认主题配置](../default-theme-config/README.md). ## Markdown @@ -145,46 +145,46 @@ Provide config options to the used theme. The options will vary depending on the - Type: `boolean` - Default: `undefined` -Whether to show line numbers to the left of each code blocks. +是否在每个代码块的左侧显示行号。 -**Also see:** +**另请参阅：** -- [Line Numbers](../guide/markdown.md#line-numbers) +- [行号](../guide/markdown.md#行号) ### markdown.slugify - Type: `Function` - Default: [source](https://github.com/vuejs/vuepress/blob/master/lib/markdown/slugify.js) -Function for transforming header texts into slugs. This affects the ids/links generated for header anchors, table of contents and sidebar links. +将标题文本转换为别名(slug)的函数。这会影响标题锚点、目录和侧边栏链接生成的 id 和链接。（译者注：此功能是为了解决非 ASCII 码字符生成链接时的 [bug](https://github.com/vuejs/vuepress/issues/45)，具体代码查看 /lib/markdown/slugify 的 slugify 函数） ### markdown.externalLinks - Type: `Object` - Default: `{ target: '_blank', rel: 'noopener noreferrer' }` -The key and value pair will be added to `` tags that points to an external link. The default option will open external links in a new window. +键和值对将被添加到指向外部链接的 `` 标签。默认选项将在新窗口中打开外部链接。 ### markdown.anchor - Type: `Object` - Default: `{ permalink: true, permalinkBefore: true, permalinkSymbol: '#' }` -Options for [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor). (Note: prefer `markdown.slugify` if you want to customize header ids.) +[markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor) 的选项。(注意：如果你想自定义标题 id 的话尽量使用 `markdown.slugify`。) ### markdown.toc - Type: `Object` - Default: `{ includeLevel: [2, 3] }` -Options for [markdown-it-table-of-contents](https://github.com/Oktavilla/markdown-it-table-of-contents). (Note: prefer `markdown.slugify` if you want to customize header ids.) +[markdown-it-table-of-contents](https://github.com/Oktavilla/markdown-it-table-of-contents) 的选项。(注意：如果你想自定义标题 id 的话尽量使用 `markdown.slugify`。) ### markdown.config - Type: `Function` - Default: `undefined` -A function to modify default config or apply additional plugins to the [markdown-it](https://github.com/markdown-it/markdown-it) instance used to render source files. Example: +修改默认配置，或将额外的插件应用于渲染源文件的 [markdown-it](https://github.com/markdown-it/markdown-it) 实例的函数。例如： ``` js module.exports = { @@ -197,49 +197,49 @@ module.exports = { } ``` -## Build Pipeline +## 建立管道(build pipeline) ### postcss - Type: `Object` - Default: `{ plugins: [require('autoprefixer')] }` -Options for [postcss-loader](https://github.com/postcss/postcss-loader). Note specifying this value will overwrite autoprefixer and you will need to include it yourself. +[postcss-loader](https://github.com/postcss/postcss-loader) 的选项。注意：指定这个值将会覆盖 autoprefixer，你需要把 autoprefixer 的选项也包含进去。 ### stylus - Type: `Object` - Default: `{ preferPathResolver: 'webpack' }` -Options for [stylus-loader](https://github.com/shama/stylus-loader). +提供给 [stylus-loader](https://github.com/shama/stylus-loader) 的参数。 ### scss - Type: `Object` - Default: `{}` -Options for [sass-loader](https://github.com/webpack-contrib/sass-loader) to load `*.scss` files. +提供给 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的参数，用来加载 `*.scss` 文件。 ### sass - Type: `Object` - Default: `{ indentedSyntax: true }` -Options for [sass-loader](https://github.com/webpack-contrib/sass-loader) to load `*.sass` files. +提供给 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的参数，用来加载 `*.sass` 文件。 ### less - Type: `Object` - Default: `{}` -Options for [less-loader](https://github.com/webpack-contrib/less-loader). +提供给 [less-loader](https://github.com/webpack-contrib/less-loader) 的参数。 ### configureWebpack - Type: `Object | Function` - Default: `undefined` -Modify the internal webpack config. If the value is an Object, it will be merged into the final config using [webpack-merge](https://github.com/survivejs/webpack-merge); If the value is a function, it will receive the config as the 1st argument and an `isServer` flag as the 2nd argument. You can either mutate the config directly, or return an object to be merged: +修改内部 webpack 配置。如果该值是一个对象，它将被合并到使用 [webpack-merge](https://github.com/survivejs/webpack-merge) 的最终配置中；如果该值是一个函数，它将接收 config 作为第一个参数，并将 `isServer` 这个标志作为第二个参数。你可以直接改变配置，或者返回一个要合并的对象： ``` js module.exports = { @@ -256,7 +256,7 @@ module.exports = { - Type: `Function` - Default: `undefined` -Modify the internal webpack config with [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). +使用 [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain) 修改内部的 webpack 配置。 ``` js module.exports = { @@ -266,11 +266,11 @@ module.exports = { } ``` -## Browser Compatibility +## 浏览器兼容性(browser compatibility) ### evergreen - Type: `boolean` - Default: `false` -Set to `true` if you are only targeting evergreen browsers. This will disable ES5 transpilation and polyfills for IE, and result in faster builds and smaller files. +如果你只针对常青树浏览器，请设置为 `true` 。这将禁用 IE5 的 ES5 转码和 polyfill，导致更快的构建和更小的文件。 diff --git a/docs/default-theme-config/README.md b/docs/default-theme-config/README.md index 6781942910..c9912003ca 100644 --- a/docs/default-theme-config/README.md +++ b/docs/default-theme-config/README.md @@ -2,46 +2,46 @@ sidebar: auto --- -# Default Theme Config +# 默认主题配置(default theme config) -::: tip -All options listed on this page apply to the default theme only. If you are using a custom theme, the options may be different. +::: tip 提示 +此页面上列出的所有选项仅适用于默认主题。如果你使用的是自定义主题，则选项可能会有所不同。 ::: -## Homepage +## 主页(homepage) -The default theme provides a homepage layout (which is used on [the homepage of this very website](../README.md)). To use it, specify `home: true` plus some other metadata in your root `README.md`'s [YAML front matter](../guide/markdown.md#front-matter). This is the actual data used on this site: +默认主题提供了一个主页布局（用于[该网站的主页](/README.md)）。要使用它，需要在你的根目录 `README.md` 的 [YAML front matter](../guide/markdown.md#front-matter) 中指定 `home：true`，并加上一些其他的元数据。这是本网站使用的实际数据： ``` yaml --- home: true heroImage: /hero.png -actionText: Get Started → +actionText: 起步 → actionLink: /guide/ features: -- title: Simplicity First - details: Minimal setup with markdown-centered project structure helps you focus on writing. -- title: Vue-Powered - details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue. -- title: Performant - details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded. +- title: 简明优先 + details: 对以 markdown 为中心的项目结构，做最简化的配置，帮助你专注于创作。 +- title: Vue 驱动 + details: 享用 Vue + webpack 开发环境，在 markdown 中使用 Vue 组件，并通过 Vue 开发自定义主题。 +- title: 性能高效 + details: VuePress 将每个页面生成为预渲染的静态 HTML，每个页面加载之后，然后作为单页面应用程序(SPA)运行。 footer: MIT Licensed | Copyright © 2018-present Evan You --- ``` -Any additional content after the `YAML front matter` will be parsed as normal markdown and rendered after the features section. +`YAML front matter` 的内容之后的其他任意内容，将被解析为正常 markdown，并在 features 部分之后渲染。 -If you want to use a completely custom homepage layout, you can also use a [Custom Layout](#custom-layout-for-specific-pages). +如果你想彻底自定义主页的布局，你还可以使用[自定义布局](#custom-layout-for-specific-pages) -## Navbar +## 导航栏(navbar) -The Navbar may contain your page title, [Search Box](#search-box), [Navbar Links](#navbar-links), [Languages](../guide/i18n.md) and [Repository Link](#git-repo-and-edit-links), all of them depends on your configuration. +导航栏包括页面标题、[搜索框](#search-box), [导航栏链接](#navbar-links)、[多语言支持](../guide/i18n.md) 和 [仓库链接](#git-repo-and-edit-links)，它们都取决于你的配置。 -### Navbar Links +### 导航栏链接(navbar links) -You can add links to the navbar via `themeConfig.nav`: +你可以通过 `themeConfig.nav` 将链接添加到导航栏中： ``` js // .vuepress/config.js @@ -56,7 +56,7 @@ module.exports = { } ``` -These links can also be dropdown menus if you provide an array of `items` instead of a `link`: +如果你提供一个 `items` 而不是 `link` 的数组，这些链接也可以是下拉菜单： ```js module.exports = { @@ -74,7 +74,7 @@ module.exports = { } ``` -In addition, you can have sub groups inside a dropdown by having nested items: +另外，你可以通过嵌套的 items 在下拉菜单中设置子分组： ```js module.exports = { @@ -92,9 +92,9 @@ module.exports = { } ``` -### Disable the Navbar +### 禁用导航栏 -To disable the navbar globally, use `themeConfig.navbar`: +可以使用 `themeConfig.navbar`，来禁用某个特定页面的导航栏： ``` js // .vuepress/config.js @@ -105,7 +105,7 @@ module.exports = { } ``` -You can disable the navbar for a specific page via `YAML front matter`: +你可以通过 `YAML front matter` 来禁用一个指定页面的导航栏： ``` yaml --- @@ -113,9 +113,9 @@ navbar: false --- ``` -## Sidebar +## 侧边栏(sidebar) -To enable the sidebar, use `themeConfig.sidebar`. The basic configuration expects an Array of links: +要启用侧边栏, 请使用 `themeConfig.sidebar`。基本的配置需要一个链接数组： ``` js // .vuepress/config.js @@ -130,13 +130,13 @@ module.exports = { } ``` -You can omit the `.md` extension, and paths ending with `/` are inferred as `*/README.md`. The text for the link is automatically inferred (either from the first header in the page or explicit title in `YAML front matter`). If you wish to explicitly specify the link text, use an Array in form of `[link, text]`. +你可以省略 `.md` 扩展名，以 `/` 结尾的路径被推断为 `*/README.md` 。该链接的文本是自动推断的（从页面的第一个标题或 `YAML front matter` 中的显式标题）。如果你希望明确指定链接文本，请使用 `[link,text]` 形式的数组。 -### Nested Header Links +### 嵌套标题链接(nested header links) -The sidebar automatically displays links for headers in the current active page, nested under the link for the page itself. You can customize this behavior using `themeConfig.sidebarDepth`. The default depth is `1`, which extracts the `h2` headers. Setting it to `0` disables the header links, and the max value is `2` which extracts both `h2` and `h3` headers. +侧边栏自动显示当前激活页面中标题的链接，嵌套在页面本身的链接下。你可以使用 `themeConfig.sidebarDepth` 自定义此行为。默认深度是 `1`，它提取 `h2` 标题。将其设置为 `0` 将禁用标题链接，最大值为`2`，同时提取 `h2` 和 `h3` 标题。 -A page can also override this value in using `YAML front matter`: +页面也可以在使用 `YAML front matter` 时覆盖此值： ``` md --- @@ -144,37 +144,37 @@ sidebarDepth: 2 --- ``` -### Displaying Header Links of All Pages +### 显示所有页面的标题链接 -The sidebar only displays links for headers in the current active page. You can display all header links for every page with `themeConfig.displayAllHeaders: true`: +默认情况下，侧边栏只会显示由当前活动页面的标题（headers）组成的链接，你可以将 `themeConfig.displayAllHeaders` 设置为 `true` 来显示所有页面的标题链接： ``` js module.exports = { themeConfig: { - displayAllHeaders: true // Default: false + displayAllHeaders: true // 默认值：false } } ``` -### Active Header Links +### 激活的标题链接 -By default, the nested header links and the hash in the URL are updated as the user scrolls to view the different sections of the page. This behavior can be disabled with the following theme config: +默认情况下，当用户滚动页面，查看不同部分时，嵌套的标题链接和 URL 中的哈希值会随之更新，此行为可以通过以下的主题配置来禁用： ``` js module.exports = { themeConfig: { - activeHeaderLinks: false, // Default: true + activeHeaderLinks: false, // 默认值：true } } ``` -::: tip - It is worth mentioning that when you disable this option, the corresponding script of this functionality will not be loaded. This is a small point in our performance optimization. +::: tip 提示 + 值得一提的是，当你禁用此选项时，此功能相应的脚本将不会被加载，这是我们性能优化的一个小技巧。 ::: -### Sidebar Groups +### 侧边栏分组(sidebar groups) -You can divide sidebar links into multiple groups by using objects: +你可以使用对象将侧边栏链接分成多个分组： ``` js // .vuepress/config.js @@ -197,11 +197,11 @@ module.exports = { } ``` -Sidebar groups are collapsable by default. You can force a group to be always open with `collapsable: false`. +侧边栏分组默认情况下是可折叠的。你可以强制一个分组始终以 `collapsable：false` 打开。 -### Multiple Sidebars +### 多个侧边栏(multiple sidebars) -If you wish to display different sidebars for different sections of content, first organize your pages into directories for each desired section: +如果你希望为不同的内容部分显示不同的侧边栏，请先组织你的页面，放到每个要求部分的目录中: ``` . @@ -218,7 +218,7 @@ If you wish to display different sidebars for different sections of content, fir └─ four.md ``` -Then, update your configuration to define your sidebar for each section. +然后，修改你的配置，将每个页面定义到不同的侧边栏中。 ``` js // .vuepress/config.js @@ -237,7 +237,7 @@ module.exports = { 'four' /* /bar/four.html */ ], - // fallback + // 回退(fallback)侧边栏配置 '/': [ '', /* / */ 'contact', /* /contact.html */ @@ -248,15 +248,15 @@ module.exports = { } ``` -::: warning -Make sure to define the fallback configuration last. +::: warning 警告 +请确保将回退(fallback)侧边栏，定义在配置的最后。 -VuePress checks each sidebar config from top to bottom. If the fallback configuration was first, VuePress would incorrectly match `/foo/` or `/bar/four.html` because they both start with `/`. +VuePress 会按从上到下的顺序，遍历侧边栏配置。如果回退侧边栏定义在第一位，VuePress 会无法正确的匹配 `/foo/` 或 `/bar/four.html`，因为他们都以 `/` 为开始。 ::: -### Auto Sidebar for Single Pages +### 自动生成侧栏(auto sidebar for single pages) -If you wish to automatically generate a sidebar that contains only the header links for the current page, you can use `YAML front matter` on that page: +如果你希望自动生成仅包含当前页面的标题链接的侧边栏，可以在该页面上使用 `YAML front matter`： ``` yaml --- @@ -264,7 +264,7 @@ sidebar: auto --- ``` -You can also enable it in all pages by using config: +你也可以通过配置来在所有页面中启用它： ``` js // .vuepress/config.js @@ -275,7 +275,7 @@ module.exports = { } ``` -In [multi-language](../guide/i18n.md) mode, you can also apply it to a specific locale: +在 [多语言](../guide/i18n.md) 模式下, 你也可以将其应用到某一特定的语言下： ``` js // .vuepress/config.js @@ -288,9 +288,9 @@ module.exports = { } ``` -### Disabling the Sidebar +### 禁用侧边栏(disabling the sidebar) -You can disable the sidebar on a specific page with `YAML front matter`: +你可以使用 `YAML front matter` 禁用特定页面上的侧边栏： ``` yaml --- @@ -298,11 +298,11 @@ sidebar: false --- ``` -## Search Box +## 搜索框(search box) -### Built-in Search +### 内置搜索(built-in search) -You can disable the built-in search box with `themeConfig.search: false`, and customize how many suggestions to be shown with `themeConfig.searchMaxSuggestions`: +可以通过 `themeConfig.search: false` 禁用内置搜索框，以及通过 `themeConfig.searchMaxSuggestions` 来调整搜索框显示的搜索提示数量： ``` js module.exports = { @@ -314,12 +314,12 @@ module.exports = { ``` ::: tip -Built-in Search only builds index from the title, `h2` and `h3` headers, if you need full text search, you can use [Algolia Search](#algolia-search). +如果你需要全文搜索，内置搜索只能从标题 `h2` 和 `h3` 标题构建索引，你可以使用 [Algolia 搜索](#algolia-search)。 ::: ### Algolia Search -The `themeConfig.algolia` option allows you to use [Algolia DocSearch](https://community.algolia.com/docsearch/) to replace the simple built-in search. To enable it, you need to provide at least `apiKey` and `indexName`: +可以通过 `themeConfig.algolia` 选项，来用 [Algolia DocSearch](https://community.algolia.com/docsearch/) 替换内置搜索。要启用 Algolia 搜索，至少需要提供 `apiKey` 和 `indexName`： ``` js module.exports = { @@ -332,15 +332,15 @@ module.exports = { } ``` -::: warning Note -Unlike the [built-in search](#built-in-search) engine which works out of the box, [Algolia DocSearch](https://community.algolia.com/docsearch/) requires you to submit your site to them for indexing before it starts working. +::: warning 注意 +不同于开箱即用的 [内置搜索](#内置搜索)，[Algolia 搜索](https://community.algolia.com/docsearch/) 需要你在使用之前将你的网站提交给它们用于创建索引。 ::: -For more options, refer to [Algolia DocSearch's documentation](https://github.com/algolia/docsearch#docsearch-options). +更多信息，请参考 [Algolia DocSearch 文档](https://github.com/algolia/docsearch#docsearch-options)。 -## Last Updated +## 最近更新 -The `themeConfig.lastUpdated` option allows you to get the UNIX timestamp(ms) of each file's last `git` commit, and it will also display at the bottom of each page with a appropriate format: +`themeConfig.lastUpdated` 选项允许你获取每个文件的最后一次 git 提交的 UNIX 时间戳（ms），并且它也会以合适的格式显示在每个页面的底部： ``` js module.exports = { @@ -350,15 +350,46 @@ module.exports = { } ``` -Note that it's `off` by default. If given `string`, it will be displayed as a prefix (default value: `Last Updated`). +请注意，它默认是关闭的，如果给定一个 `string` 类型的值，它将会作为前缀显示（默认值是：`Last Updated`）。 ::: warning - Since `lastUpdated` is based on `git`, so you can only use it in a `git` repository. + 由于 `lastUpdated` 是基于 `git` 的, 所以你只能在一个基于 `git` 的项目中启用它。 +::: + +## Service Worker + +`themeConfig.serviceWorker` 选项将允许你进行 service worker 相关的配置 + +::: tip 提示 +请不要将 `themeConfig.serviceWorker` 与 [Config > serviceWorker](../config/README.md#serviceworker) 混淆，[Config > serviceWorker](../config/README.md#serviceworker) 是**站点级别的**，而 `themeConfig.serviceWorker` 是**主题级别的** +::: + +### 刷新内容的弹窗 + +开启 `themeConfig.serviceWorker.updatePopup` 选项，将开启一个能够刷新内容的弹窗。当网站更新（即 Worker 更新）时，它会提供一个 `refresh` 按钮，允许用户立刻刷新内容。 + +::: tip 提示 +如果没有 `refresh` 按钮，新的 service worker 将在所有的 [clients](https://developer.mozilla.org/en-US/docs/Web/API/Clients) 关闭后才会处于活动状态。这意味着访问者在关闭你网站的所有标签之前将无法看到新内容。但是，`refresh` 按钮可以立即激活新的 Service Worker。 ::: -## Prev / Next Links +``` js +module.exports = { + themeConfig: { + serviceWorker: { + updatePopup: true // Boolean | Object, 默认值是 undefined. + // 如果设置为 true, 默认的文本配置将是: + // updatePopup: { + // message: "New content is available.", + // buttonText: "Refresh" + // } + } + } +} +``` + +## 上一页 / 下一页链接(prev / next links) -Prev and next links are automatically inferred based on the sidebar order of the active page. You can also explicitly overwrite or disable them using `YAML front matter`: +根据激活页面的侧边栏顺序自动推断上一个和下一个链接。你也可以使用 `YAML front matter` 来显式覆盖或禁用它们： ``` yaml --- @@ -367,37 +398,37 @@ next: false --- ``` -## Git Repo and Edit Links +## Git 仓库和编辑链接 -Providing `themeConfig.repo` auto generates a GitHub link in the navbar and "Edit this page" links at the bottom of each page. +提供 `themeConfig.repo` 会在导航栏中自动生成一个 GitHub 链接，并在每个页面的底部显示「编辑此页面」链接。 ``` js // .vuepress/config.js module.exports = { themeConfig: { - // Assumes GitHub. Can also be a full GitLab url. + // 假定 GitHub。也可以是一个完整的 GitLab URL。 repo: 'vuejs/vuepress', - // Customising the header label - // Defaults to "GitHub"/"GitLab"/"Bitbucket" depending on `themeConfig.repo` - repoLabel: 'Contribute!', + // 自定义项目仓库链接文字 + // 默认根据 `themeConfig.repo` 中的 URL 来自动匹配是 "GitHub"/"GitLab"/"Bitbucket" 中的哪个，如果不设置时是 "Source"。 + repoLabel: '贡献代码！', - // Optional options for generating "Edit this page" link + // 以下为可选的 "Edit this page" 链接选项 - // if your docs are in a different repo from your main project: + // 如果你的文档和项目位于不同仓库： docsRepo: 'vuejs/vuepress', - // if your docs are not at the root of the repo: + // 如果你的文档不在仓库的根目录下： docsDir: 'docs', - // if your docs are in a specific branch (defaults to 'master'): + // 如果你的文档在某个特定的分支（默认是 'master' 分支）： docsBranch: 'master', - // defaults to false, set to true to enable + // 默认为 false，设置为 true 来启用 editLinks: true, - // custom text for edit link. Defaults to "Edit this page" - editLinkText: 'Help us improve this page!' + // 自定义编辑链接的文本。默认是 "Edit this page" + editLinkText: '帮助我们改进页面内容！' } } ``` -You can also hide the edit link on a specific page via `YAML front matter`: +你还可以通过 `YAML front matter` 隐藏指定页面上的编辑链接： ``` yaml --- @@ -405,56 +436,52 @@ editLink: false --- ``` -## Simple CSS Override +## 简单的 CSS 覆盖 -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. +如果你希望对默认主题的样式应用简单的覆盖，可以创建一个 `.vuepress/override.styl` 文件。 这是 [Stylus](http://stylus-lang.com/) 文件，但你也可以使用普通的 CSS 语法。 -There are a few color variables you can tweak: +有几个颜色变量可以调整： ``` stylus -// showing default values +// 显示默认值 $accentColor = #3eaf7c $textColor = #2c3e50 $borderColor = #eaecef $codeBgColor = #282c34 ``` -### Existing issues - -In order to override the default variables mentioned above, `override.styl` will be imported at the end of the `config.styl` in default theme, and this file will be used by multiple files, so once you wrote styles here, your style will be duplicated by multiple times. See [#637](https://github.com/vuejs/vuepress/issues/637). +### 仍然存在的问题 -In fact, `style constants override` and `styles override` are two things, the former should be executed before any CSS is compiled, while the latter should be generated at the end of the CSS bundle, which has the highest priority. +为了覆盖上面提到的默认变量，`override.styl` 将在默认主题的 `config.styl` 末尾导入，这个文件将被多个文件使用，所以一旦你在这里写了样式，你的 样式将被多次复制。参考 [#637](https://github.com/vuejs/vuepress/issues/637)。 -### Migrate your styles to `style.styl` +### 迁移你的样式到 `style.styl` -Start from `0.12.0`, we split `override.styl` into two APIs: `override.styl` and `style.styl`: +事实上，`style constants override` 和 `styles override` 是两个东西，前者应该在编译 CSS 之前执行，而后者应该在 CSS bundle 末尾生成，它具有最高优先级。 -If you wrote styles at `override.styl` in the past, e.g. +从 `0.12.0` 开始，我们将 `override.styl` 分成两个 API：`override.styl` 和 `style.styl` 。如果你以前在 `override.styl` 中编写样式，例如： ``` stylus -// override.styl -$textColor = red // style constants override +// .vuepress/override.styl +$textColor = red // stylus constants override. -#my-style {} // styles override or custom styles. +#my-style {} // your extra styles. ``` -You'll need to separate the style part to `style.styl`: +你需要抽离这部分样式到 `style.styl`: ``` stylus -// override.styl -// SHOULD ONLY focus on style constants override. +// .vuepress/override.styl, SHOULD ONLY contain "stylus constants override". $textColor = red ``` ``` stylus -// style.styl -// SHOULD focus on styles override or your custom styles. +// .vuepress/style.styl, your extra styles. #my-style {} ``` -## Custom Page Class +## 自定义页面的 class -Sometimes, you may need to add a unique class for a specific page so that you can target content on that page only in custom CSS. You can add a class to the theme container div with `pageClass` in `YAML front matter`: +有时，你可能需要为特定的页面添加一个唯一的 class，以便你只能在自定义 CSS 中定位该页面上的内容。 你可以在 `YAML front matter` 中用 `pageClass` 在主题的容器 div 中添加一个 class： ``` yaml --- @@ -462,19 +489,19 @@ pageClass: custom-page-class --- ``` -Then you can write CSS targeting that page only: +然后你就可以只编写针对该页面的 CSS： ``` css /* .vuepress/override.styl */ .theme-container.custom-page-class { - /* page-specific rules */ + /* 页面特定的规则 */ } ``` -## Custom Layout for Specific Pages +## 特定页面的自定义布局(custom layout for specific pages) -By default the content of each `*.md` file is rendered in a `
` container, along with the sidebar, auto-generated edit links and prev/next links. If you wish to use a completely custom component in place of the page (while only keeping the navbar), you can again specify the component to use using `YAML front matter`: +默认情况下，每个 `*.md` 文件的内容都会显示在一个 `
` 容器中，以及侧边栏，自动生成的编辑链接和 prev/next 链接。如果你希望使用完全自定义的组件代替页面（同时只保留导航栏），则可以使用 `YAML front matter` 再次指定要使用的组件： ``` yaml --- @@ -482,8 +509,8 @@ layout: SpecialLayout --- ``` -This will render `.vuepress/components/SpecialLayout.vue` for the given page. +这将为给定页面渲染 `.vuepress/components/SpecialLayout.vue`。 -## Ejecting +## 弹出(ejecting) -You can copy the default theme source code into `.vuepress/theme` to fully customize the theme using the `vuepress eject [targetDir]` command. Note, however, once you eject, you are on your own and won't be receiving future updates or bug fixes to the default theme even if you upgrade VuePress. +你可以将默认主题的源代码复制到 `.vuepress/theme` 中，来使用 `vuepress eject [targetDir]` 命令彻底自定义主题。但是请注意，一旦你 eject，即使你升级 VuePress 版本，你这仍然是自己的主题，并且不会收到对默认主题的未来更新或错误修复。 diff --git a/docs/guide/README.md b/docs/guide/README.md index 2ab95d5003..dd68aca559 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -1,59 +1,59 @@ -# 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. It was created to support the documentation needs of Vue's own sub projects. +VuePress 由两部分组成：一个以 Vue 驱动的主题系统的简约静态网站生成工具，和一个为编写技术文档而优化的默认主题。它是为了支持 Vue 子项目的文档需求而创建的。 -Each page generated by VuePress has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly. Once the page is loaded, however, Vue takes over the static content and turns it into a full Single-Page Application (SPA). Additional pages are fetched on demand as the user navigates around the site. +由 VuePress 生成的每个页面，都具有相应的预渲染静态 HTML，它们能提供出色的加载性能，并且对 SEO 友好。然而，页面加载之后，Vue 就会将这些静态内容，接管为完整的单页面应用程序(SPA)。当用户在浏览站点时，可以按需加载其他页面。 -## How It Works +## 运行原理(how it works) -A VuePress site is in fact a 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!). +VuePress 网站实际上是由 [Vue](http://vuejs.org/), [Vue Router](https://github.com/vuejs/vue-router) 和 [webpack](http://webpack.js.org/) 驱动的单页面应用程序。如果你以前使用过 Vue，那么在编写或开发自定义主题时（甚至可以使用 Vue DevTools 来调试你的自定义主题！），你会融入到熟悉的开发体验中！ -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/). +在构建过程中，我们会创建应用程序的服务器渲染版本，并且实际上是通过访问每个路由，来渲染相应的 HTML。这种方式受到 [Nuxt](https://nuxtjs.org/) 的 `nuxt generate` 命令以及 [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. +每个 markdown 文件都使用 [markdown-it](https://github.com/markdown-it/markdown-it) 编译为 HTML，然后作为 Vue 组件的模板进行处理。这允许你直接在 markdown 文件中使用 Vue，在需要嵌入动态内容时，这种使用方式非常有用。 -## Features +## 特性(features) -- [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-themes.md) -- [Automatic Service Worker generation](../config/README.md#serviceworker) -- [Google Analytics Integration](../config/README.md#ga) -- ["Last Updated" based on Git](../default-theme-config/README.md#last-updated) -- [Multi-language support](./i18n.md) -- A default theme with: - - Responsive layout - - [Optional Homepage](../default-theme-config/README.md#homepage) - - [Simple out-of-the-box header-based search](../default-theme-config/README.md#built-in-search) - - [Algolia Search](../default-theme-config/README.md#algolia-search) - - Customizable [navbar](../default-theme-config/README.md#navbar) and [sidebar](../default-theme-config/README.md#sidebar) - - [Auto-generated GitHub link and page edit links](../default-theme-config/README.md#git-repo-and-edit-links) +- [内置 markdown 扩展](./markdown.md)，针对技术文档进行了优化 +- [能够利用内嵌在 markdown 文件中的 Vue 代码](./using-vue.md) +- [以 Vue 驱动的自定义主题系统](./custom-themes.md) +- [自动生成 Service Worker](../config/README.md#serviceworker) +- [Google Analytics 集成](../config/README.md#ga) +- [基于 Git 的"最近更新"](../default-theme-config/README.md#最近更新) +- [多语言支持](./i18n.md) +- 一个默认主题包括： + - 响应式布局 + - [可选的主页](../default-theme-config/README.md#主页-homepage) + - [简单、开箱即用、基于标题的搜索功能](../default-theme-config/README.md#内置搜索-built-in-search) + - [Algolia 搜索](../default-theme-config/README.md#algolia-search) + - 可定制的[导航栏](../default-theme-config/README.md#导航栏-navbar)和[侧边栏](../default-theme-config/README.md#侧边栏-sidebar) + - [自动生成的 GitHub 链接和页面编辑链接](../default-theme-config/README.md#git-仓库和编辑链接) -## Todo +## 待实现特性(todo) -VuePress is still a work in progress. There are a few things that it currently does not support but are planned: +VuePress 的开发仍在进行中。有几件目前不支持，但计划做的功能： -- Plugin support -- Blogging support +- 插件支持 +- 博客支持 -Contributions are welcome! +欢迎贡献！ -## Why Not ...? +## 为什么不使用下面这些工具？ ### 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. +VuePress 能做的事情，Nuxt 也同样能够实现，但是，它是为构建应用程序而设计的。而 VuePress 专注于以内容为中心的静态网站，并且为开箱即用的技术文档，提供量身定制的功能。 ### Docsify / Docute -Both are great projects and also Vue-powered. Except they are both completely runtime-driven and therefore not SEO-friendly. If you don't care about SEO and don't want to mess with installing dependencies, these are still great choices. +二者都是伟大的项目，也都是以 Vue 驱动。但它们完全是运行时驱动(runtime-driven)的项目，因此不适合 SEO 优化。如果你不关心 SEO 优化，也不想因为安装依赖而扰乱心神，这些仍然是不错的选择。 ### Hexo -Hexo has been serving the Vue docs well - 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. +Hexo 一直在为 Vue 文档提供服务 - 事实上，离我们的主站完全迁移到 VuePress，可能还要经过一段时间。其中最大的问题是，它的主题系统是非常静态和基于字符串的 - 我们确实需要利用 Vue 来实现布局和交互。此外，无法对 Hexo 的 markdown 渲染，进行极其灵活的配置。 ### GitBook -We've been using GitBook for most of our sub project docs. The primary problem with GitBook is that its development reload performance is intolerable with a large amount of files. The default theme also has a pretty limiting navigation structure, and the theming system is, again, not Vue based. The team behind GitBook is also more focused on turning it into a commercial product rather than an open-source tool. +我们大部分的子项目文档中已经使用了 GitBook。GitBook 的主要问题是有大量文件时，它的开发重载性能简直令人无法容忍。它的默认主题也只有一个非常有限的导航结构，并且主题系统也不是基于 Vue 的。GitBook 背后的团队也更注重将其打造为一个商业产品，而不是开源工具。 diff --git a/docs/guide/assets.md b/docs/guide/assets.md index 04a6eb31fe..218ae025ee 100644 --- a/docs/guide/assets.md +++ b/docs/guide/assets.md @@ -1,23 +1,23 @@ -# Asset Handling +# 静态资源处理 -## Relative URLs +## 相对 URLs -All markdown files are compiled into Vue components and processed by webpack, therefore you can and **should prefer** referencing any asset using relative URLs: +所有 markdown 文件都会被编译到 Vue 组件中并由 webpack 处理，因此你**应该更倾向于**使用相对 URL 引用任意资源： ``` md ![An image](./image.png) ``` -This would work the same way as in `*.vue` file templates. The image will be processed with `url-loader` and `file-loader`, and copied to appropriate locations in the generated static build. +这将和 `* .vue` 文件模板中的运作的方式相同。该图片资源将通过 `url-loader` 和 `file-loader` 进行处理，并被复制到生成的静态构建文件中的合适位置。 -In addition, you can use the `~` prefix to explicitly indicate this is a webpack module request, allowing you to reference files with webpack aliases or from npm dependencies: +另外，你可以使用 `~` 前缀来明确指出这是一个 webpack 模块请求，这将允许你使用 webpack 别名或 npm 依赖关系引用文件： ``` md ![Image from alias](~@alias/image.png) ![Image from dependency](~some-dependency/image.png) ``` -webpack aliases can be configured via [configureWebpack](/config/#configurewebpack) in `.vuepress/config.js`. Example: +webpack 别名可以通过 `.vuepress/config.js` 中的 [configureWebpack](/config/#configurewebpack) 进行配置。例如： ``` js module.exports = { @@ -31,20 +31,20 @@ module.exports = { } ``` -## Public Files +## 公共文件 -Sometimes you may need to provide static assets that are not directly referenced in any of your markdown or theme components - for example, favicons and PWA icons. In such cases you can put them inside `.vuepress/public` and they will be copied to the root of the generated directory. +有时，你可能需要提供静态资源，这些资源并没有在任何 markdown 或主题组件中直接引用 - 例如，favicons 和 PWA 图标。在这种情况下，你可以将它们放在 `.vuepress/public` 中，并且它们将被复制到生成目录的根目录。 -## Base URL +## 基准 URL -If your site is deployed to a non-root URL, you will need to set the `base` option in `.vuepress/config.js`. For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `"/bar/"` (it should always start and end with a slash). +如果你的网站部署到非根 URL，则需要在 `.vuepress/config.js` 中设置 `base` 选项。例如，如果你打算将你的网站部署到 `https://foo.github.io/bar/`，那么`base`应该设置为 `"/bar/"`（它应该始终以斜杠开始和结束）。 -With a base URL, if you want to reference an image in `.vuepress/public`, you'd have to use URLs like `/bar/image.png`. However, this is brittle if you ever decide to change the `base` later. To help with that, VuePress provides a built-in helper `$withBase` (injected onto Vue's prototype) that generates the correct path: +使用基准 URL，如果你想在 `.vuepress/public` 中引用图片，则必须使用像 `/bar/image.png` 这样的 URL。但是，如果你有朝一日会决定更改 `base` ，这样的路径就显得很脆弱了。为了解决这个问题，VuePress 提供了一个内置的帮助器 `$withBase`（注入到 Vue 的原型中），它可以生成正确的路径： ``` vue foo ``` -Note you can use the above syntax not only in theme components, but in your markdown files as well. +请注意，你不仅可以在主题组件中使用上述语法，还可以在 markdown 文件中使用上述语法。 -In addition, if a `base` is set, it is automatically prepended to all asset URLs in `.vuepress/config.js` options. +另外，如果设置了 `base`，它会自动作为前缀拼接到 `.vuepress/config.js` 选项中的所有静态资源 URL 中。 diff --git a/docs/guide/basic-config.md b/docs/guide/basic-config.md index e333472466..8c8e369cec 100644 --- a/docs/guide/basic-config.md +++ b/docs/guide/basic-config.md @@ -1,8 +1,8 @@ -# Configuration +# 配置 -## Config File +## 配置文件(config file) -Without any configuration, the 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. Your project structure is probably like this: +不做任何配置的话，页面会显得过于简单，用户也无法方便地浏览网站。想要定制你的网站，首先需要在文档目录中创建一个 `.vuepress` 目录。这是放置所有 VuePress 特有(VuePress-specific) 文件的地方。你的项目结构可能长这样： ``` . @@ -13,7 +13,7 @@ Without any configuration, the page is pretty minimal, and the user has no way t └─ package.json ``` -The essential file for configuring a VuePress site is `.vuepress/config.js`, which should export a JavaScript object: +配置 VuePress 站点的基本文件是 `.vuepress/config.js`，其中导出一个 JavaScript 对象： ``` js module.exports = { @@ -22,31 +22,31 @@ module.exports = { } ``` -If you've got the dev server running, you should see the page now has a header with the title and a search box. VuePress comes with built-in headers-based search - it automatically builds a simple search index from the title, `h2` and `h3` headers from all the pages. +如果开发服务器正常运行，你应该看到该页面现在有一个 title 标题和一个搜索框。VuePress 带有内置的 基于 header 搜索(headers-based search) 的功能 - 它会自动从所有页面的 title, `h2` 和 `h3` header 标签中，建立一个简单的搜索索引。（译者注：此搜索是遍历 pages 数组的每一项，取出其中的 headers 数组，其中数组每项对应 markdown 标题，具体代码查看 /lib/default-theme/SearchBox.vue 的 suggestions 函数） -Consult the [Config Reference](../config/README.md) for a full list of options. +请查阅 [配置参考](../config/README.md) 以获取完整的选项列表。 -::: tip Alternative Config Formats -You can also use YAML (`.vuepress/config.yml`) or TOML (`.vuepress/config.toml`) formats for the configuration file. +::: tip 可替代的配置格式 +你也可以使用 YAML(`.vuepress/config.yml`) 或 TOML(`.vuepress/config.toml`) 格式编写配置文件。 ::: -## Theme Configuration +## 主题配置(theme configuration) -A VuePress theme is responsible for all the layout and interactivity details of your site. VuePress ships with a default theme (you are looking at it right now) which is designed for technical documentation. It exposes a number of options that allow you to customize the navbar, sidebar and homepage, etc. For details, check out the [Default Theme Config](../default-theme-config/README.md) page. +VuePress 主题，负责网站的所有布局和交互细节。VuePress 附带一个默认主题（你现在看到的就是），专门为技术文档设计。它暴露许多选项，允许你自定义导航栏(navbar)、侧边栏(sidebar)和主页(homepage)等。详细信息请查看 [默认主题配置](../default-theme-config/README.md) 页面。 -If you wish to develop a custom theme, see [Custom Themes](./custom-themes.md). +如果你想开发自定义主题，请参考 [自定义主题](./custom-themes.md)。 -## App Level Enhancements +## 应用程序级别的增强功能(app level enhancements) -Since the VuePress app is a standard Vue app, you can apply app-level enhancements by creating a file `.vuepress/enhanceApp.js`, which will be imported into the app if it is present. The file should `export default` a hook function which will receive an object containing some app level values. You can use this hook to install additional Vue plugins, register global components, or add additional router hooks: +由于 VuePress 应用是一个标准的 Vue 应用程序，所以你可以通过创建一个 `.vuepress/enhanceApp.js` 文件，来使用应用程序级别的增强功能，如果此文件存在，该文件将会被导入到该应用程序中。该文件应该通过 `export default` 方式导出一个钩子函数，它将接收一个含有一些应用程序级别值的对象作为参数。你可以使用这个钩子来安装额外的 Vue 插件，注册全局组件，或者添加额外的路由钩子： ``` js export default ({ - Vue, // the version of Vue being used in the VuePress app - options, // the options for the root Vue instance - router, // the router instance for the app - siteData // site metadata + Vue, // 当前 VuePress 应用所使用的 Vue 版本 + options, // 根 Vue 实例的选项 + router, // 应用程序的路由实例 + siteData // 网站元数据 }) => { - // ...apply enhancements to the app + // ...使用应用程序级别的增强功能 } ``` diff --git a/docs/guide/custom-themes.md b/docs/guide/custom-themes.md index ffdbcf520e..784c544395 100644 --- a/docs/guide/custom-themes.md +++ b/docs/guide/custom-themes.md @@ -1,10 +1,10 @@ -# Custom Themes +# 自定义主题 -::: tip -Theme components are subject to the same [browser API access restrictions](./using-vue.md#browser-api-access-restrictions). +::: tip 提示 +主题组件同样受到[浏览器 API 访问限制](./using-vue.md#浏览器-api-访问限制)。 ::: -VuePress uses Vue single file components for custom themes. To use a custom layout, create a `.vuepress/theme` directory in your docs root, and then create a `Layout.vue` file: +VuePress 使用 Vue 单个文件组件来定制主题。要使用自定义布局，请在文档根目录下创建一个 `.vuepress/theme` 目录，然后创建一个 `Layout.vue` 文件： ``` . @@ -13,13 +13,13 @@ VuePress uses Vue single file components for custom themes. To use a custom layo    └─ Layout.vue ``` -From there it's the same as developing a normal Vue application. It is entirely up to you how to organize your theme. +这儿和开发一个正常的 Vue 应用程序是一样的。完全取决于你如何组织你的主题。 -## Site and Page Metadata +## 网站和网页元数据(site and page metadata) -The `Layout` component will be invoked once for every `.md` file in `docs`, and the metadata for the entire site and that specific page will be exposed respectively as `this.$site` and `this.$page` properties which are injected into every component in the app. +对于 `docs` 中的每个 `.md` 文件，`Layout`组件将只被调用一次，并且整个站点和该特定页面的元数据将分别暴露为 `this.$site` 和 `this.$page` 属性被注入到应用程序中的每个组件里。 -This is the value of `$site` of this very website: +这是这个网站的 `$site` 值： ``` json { @@ -38,36 +38,36 @@ This is the value of `$site` of this very website: } ``` -`title`, `description` and `base` are copied from respective fields in `.vuepress/config.js`. `pages` contains an array of metadata objects for each page, including its path, page title (explicitly specified in [YAML front matter](./markdown.md#front-matter) or inferred from the first header on the page), and any YAML front matter data in that file. +`title`，`description` 和 `base` 从 `.vuepress/config.js` 中的相应字段复制而来。 `pages` 包含每个页面的元数据对象数组，包括其路径，页面标题（在 [YAML front matter](./markdown.md#front-matter) 中显式指定或从页面上的第一个标题推断）以及该文件中的任意 YAML frontmatter 数据。 -This is the `$page` object for this page you are looking at: +这是你正在查看的此页面的 `$page` 对象： ``` json { "lastUpdated": 1524847549000, "path": "/guide/custom-themes.html", - "title": "Custom Themes", + "title": "自定义主题", "headers": [/* ... */], "frontmatter": {} } ``` -If the user provided `themeConfig` in `.vuepress/config.js`, it will also be available as `$site.themeConfig`. You can use this to allow users to customize behavior of your theme - for example, specifying categories and page order. You can then use these data together with `$site.pages` to dynamically construct navigation links. +如果用户在 `.vuepress/config.js` 中提供 `themeConfig`，它也可以用 `$site.themeConfig`。你可以使用它来允许用户自定义主题的行为 - 例如，指定类别和页面顺序。然后，你可以将这些数据与 `$site.pages` 一起使用来动态构建导航链接。 -Finally, don't forget that `this.$route` and `this.$router` are also available as part of Vue Router's API. +最后，别忘了 `this.$route` 和 `this.$router` 也可作为 Vue Router API 的一部分。 -::: tip - `lastUpdated` is the UNIX timestamp of this file's last git commit, for more details, refer to [Last Updated](../default-theme-config/README.md#last-updated). +::: tip 提示 +`lastUpdated` 是该文件最后一次 git 提交的 UNIX 时间戳，更多详细信息请参考[最近的更新](../default-theme-config/README.md#最近更新)。 ::: -## Content Excerpt +## 内容摘要(content excerpt) -If a markdown file contains a `` comment, any content above the comment will be extracted and exposed as `$page.excerpt`. If you are building custom theme for blogging, this data can be used to render a post list with excerpts. +如果 markdown 文件包含一个 `` 注释，那么注释上方的任何内容都将被提取，然后暴露在 `$page.excerpt` 中。如果你正在为博客创建自定义主题，可以使用此数据来渲染带有摘要信息的文章列表。 -## Content Outlet +## 内容出口(content outlet) -The compiled content of the current `.md` file being rendered will be available as a special `` global component. You will need to render it somewhere in your layout in order to display the content of the page. The simplest theme can be just a single `Layout.vue` component with the following content: +所渲染的当前 `.md` 文件的编译内容将作为特殊的 `` 全局组件来使用。你需要将其呈现在布局的某个位置以显示页面的内容。最简单的主题可以是一个带有以下内容的 `Layout.vue` 组件： ``` html ``` -## App Level Enhancements +## 应用级别的增强(app level enhancements) -Themes can enhance the Vue app that VuePress uses by exposing an `enhanceApp.js` file at the root of the theme. The file should `export default` a hook function which will receive an object containing some app level values. You can use this hook to install additional Vue plugins, register global components, or add additional router hooks: +主题可以通过在主题根文件的 `enhanceApp.js` 文件来增强 VuePress 使用的 Vue 应用。该文件应该通过 `export default` 命令导出一个钩子函数，并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组件，或者增加额外的路由钩子： ``` js export default ({ @@ -92,11 +92,11 @@ export default ({ } ``` -## Using Theme from a Dependency +## 从依赖中引用主题(using theme from a dependency) -Themes can be published on npm in raw Vue SFC format as `vuepress-theme-xxx`. +主题可以在 npm 上以原始 Vue SFC 格式发布为 `vuepress-theme-xxx`。 -To use a theme from an npm dependency, provide a `theme` option in `.vuepress/config.js`: +要使用 npm 依赖项的主题，请在 `.vuepress/config.js` 中提供一个 `theme` 选项： ``` js module.exports = { @@ -104,8 +104,8 @@ module.exports = { } ``` -VuePress will attempt to locate and use `node_modules/vuepress-theme-awesome/Layout.vue`. +VuePress 将尝试定位并使用 `node_modules/vuepress-theme-awesome/Layout.vue`。 -## Customizing the Default Theme +## 自定义默认主题 -The `vuepress eject [targetDir]` command will copy the default theme source code into `.vuepress/theme` to allow complete customization. Note, however, once you eject, you are on your own and won't be receiving future updates or bug fixes to the default theme even if you upgrade VuePress. +`vuepress eject [targetDir]` 命令会将默认主题的源代码复制到 `.vuepress/theme` 中，来允许彻底的自定义。但是请注意，一旦你 eject，即使你升级 VuePress 版本，你这仍然是自己的主题，并且不会收到对默认主题的未来更新或错误修复。 diff --git a/docs/guide/deploy.md b/docs/guide/deploy.md index b3d84283f4..743ab2ea04 100644 --- a/docs/guide/deploy.md +++ b/docs/guide/deploy.md @@ -1,10 +1,10 @@ -# Deploying +# 部署 -The following guides are based on a few shared assumptions: +以下指南基于几个共同的假设： -- You are placing your docs inside the `docs` directory of your project; -- You are using the default build output location (`.vuepress/dist`); -- VuePress is installed as a local dependency in your project, and you have setup the following npm scripts: +- 将文档放置在项目的 `docs` 目录中； +- 使用默认的构建输出位置（`.vuepress/dist`）。 +- VuePress 是在项目本地的依赖中安装的，并且配置如下的 npm scripts: ``` json { @@ -14,59 +14,59 @@ The following guides are based on a few shared assumptions: } ``` -## GitHub Pages +## GitHub 页面 -1. Set correct `base` in `docs/.vuepress/config.js`. +1. 在 `docs/.vuepress/config.js` 设置正确的 `base`。 - If you are deploying to `https://.github.io/`, you can omit `base` as it defaults to `"/"`. + 如果你打算部署到 `https://.github.io/`，就可以省略这一步，因为 `base` 默认为 `"/"`。 - If you are deploying to `https://.github.io//`, (i.e. your repository is at `https://github.com//`), set `base` to `"//"`. + 如果你打算部署到 `https://.github.io//`（也就是说你的仓库地址是 `https://github.com//`），设置 base 为 `"//"`。 -2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately) and run it to deploy: +2. 在你的项目中，创建一个有以下内容的 `deploy.sh` 文件（对高亮行适当注释），然后运行它完成部署： ``` bash{13,20,23} #!/usr/bin/env sh -# abort on errors +# 终止一个错误 set -e -# build +# 构建 npm run docs:build -# navigate into the build output directory +# 进入生成的构建文件夹 cd docs/.vuepress/dist -# if you are deploying to a custom domain +# 如果你是要部署到自定义域名 # echo 'www.example.com' > CNAME git init git add -A git commit -m 'deploy' -# if you are deploying to https://.github.io +# 如果你想要部署到 https://.github.io # git push -f git@github.com:/.github.io.git master -# if you are deploying to https://.github.io/ +# 如果你想要部署到 https://.github.io/ # git push -f git@github.com:/.git master:gh-pages cd - ``` ::: tip -You can also run the above script in your CI setup to enable automatic deployment on each push. +你可以在你的 CI 中，设置每次 push 代码时自动运行上述脚本。 ::: -## GitLab Pages and GitLab CI +## GitLab 页面和 GitLab CI -1. Set correct `base` in `docs/.vuepress/config.js`. +1. 在 `docs/.vuepress/config.js` 设置正确的 `base`。 - If you are deploying to `https://.gitlab.io/`, you can omit `base` as it defaults to `"/"`. + 如果你打算部署到 `https://.gitlab.io/`，就可以省略这一步，因为 `base` 默认为 `"/"`。 - If you are deploying to `https://.gitlab.io//`, (i.e. your repository is at `https://gitlab.com//`), set `base` to `"//"`. + 如果你打算部署到 `https://.gitlab.io//`（也就是说你的仓库地址是 `https://gitlab.com//`），设置 base 为 `"//"`。 -2. Set `dest` in `.vuepress/config.js` to `public`. +2. 在 `.vuepress/config.js` 中设置 `dest` 到 `public`. -3. Create a file called `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content. +3. 在你项目的根目录下创建一个名为 `.gitlab-ci.yml` 的文件，无论何时你提交更改，它都会帮助你自动构建和部署： ``` yaml image: node:9.11.1 @@ -89,18 +89,18 @@ pages: ## Netlify -1. On Netlify, setup up a new project from GitHub with the following settings: +1. 在 Netlify 中, 从 GitHub 创建一个新项目，使用以下设置： - - **Build Command:** `npm run docs:build` or `yarn docs:build` - - **Publish directory:** `docs/.vuepress/dist` + - **构建命令：** `npm run docs:build` or `yarn docs:build` + - **发布目录：** `docs/.vuepress/dist` -2. Hit the deploy button! +2. 点击部署按钮！ ## Google Firebase -1. Make sure you have [firebase-tools](https://www.npmjs.com/package/firebase-tools) installed. +1. 确保你已经安装了 [firebase-tools](https://www.npmjs.com/package/firebase-tools)。 -2. Create `firebase.json` and `.firebaserc` at the root of your project with the following content: +2. 在你项目的根目录下创建 `firebase.json` 和 `.firebaserc`，写入以下内容： `firebase.json`: ```json @@ -121,31 +121,31 @@ pages: } ``` -3. After running `yarn docs:build` or `npm run docs:build`, deploy with the command `firebase deploy`. +3. 执行 `yarn docs:build` 或 `npm run docs:build` 之后，使用 `firebase deploy` 命令来部署。 ## Surge -1. First install [surge](https://www.npmjs.com/package/surge), if you haven't already. +1. 首先先安装好 [surge](https://www.npmjs.com/package/surge)。 -2. Run `yarn docs:build` or `npm run docs:build`. +2. 运行 `yarn docs:build` 或 `npm run docs:build`。 -3. Deploy to surge, by typing `surge docs/.vuepress/dist`. +3. 要部署到 surge, 运行 `surge docs/.vuepress/dist` 命令。 -You can also deploy to a [custom domain](http://surge.sh/help/adding-a-custom-domain) by adding `surge docs/.vuepress/dist yourdomain.com`. +你也可以通过 `surge docs/.vuepress/dist yourdomain.com` 来部署到 [自定义域名(http://surge.sh/help/adding-a-custom-domain)。 ## Heroku -1. First install [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli). +1. 首先要安装 [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli)。 -2. Create a Heroku account [here](https://signup.heroku.com). +2. [在这里](https://signup.heroku.com)创建一个 Heroku 账号。 + +3. 运行 `heroku login` 并填写你的 Heroku 证书： -3. Run `heroku login` and fill in your Heroku credentials: - ``` bash heroku login ``` -4. Create a file called `static.json` in the root of your project with the content below: +4. 在你的项目根目录中，创建一个名为 `static.json` 的文件，里面有下述内容： `static.json`: ```json @@ -154,29 +154,33 @@ You can also deploy to a [custom domain](http://surge.sh/help/adding-a-custom-do } ``` -This is the configuration of your site. see more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static). +这就是你项目的配置，请参考 [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static) 了解更多。 -5. Set up your Heroku git remote: +5. 配置 Heroku 的 git 远程仓库： ``` bash -# version change +# 版本变化 git init git add . git commit -m "My site ready for deployment." -# creates a new app with a specified name +# 用指定的名称创建一个新的 heroku 应用 heroku apps:create example -# set buildpack for static sites +# 为静态站点设置构建包(buildpack) heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git ``` -6. Deploying Your Site +6. 部署你的站点 ``` bash -# publish site +# 发布站点 git push heroku master -# opens a browser to view the Dashboard version of Heroku CI +# 打开一个浏览器去opens a browser to view the Dashboard version of Heroku CI heroku open ``` + +*** + +> 原文：[https://vuepress.vuejs.org/guide/deploy.html](https://vuepress.vuejs.org/guide/deploy.html) diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index ab48f0ad6b..b2ba2da50e 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -1,46 +1,46 @@ -# Getting Started +# 起步 -::: warning COMPATIBILITY NOTE -VuePress requires Node.js >= 8. +::: warning 兼容性注意事项 +VuePress 要求 Node.js >= 8。 ::: -## Global Installation +## 全局安装 -If you just want to play around with VuePress, you can install it globally: +如果你只是想随便用下 VuePress，你可以在全局安装它： ``` bash -# install globally -yarn global add vuepress # OR npm install -g vuepress +# 全局安装 +yarn global add vuepress # 或 npm install -g vuepress -# create a markdown file +# 创建一个 markdown 文件 echo '# Hello VuePress' > README.md -# start writing +# 开始编写文档 vuepress dev -# build +# 构建 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. +如果你想要在一个已有项目中维护文档，就应该将 VuePress 安装为本地依赖。此设置还允许你使用 CI 或 Netlify 服务，在推送时自动部署。 ``` bash -# install as a local dependency -yarn add -D vuepress # OR npm install -D vuepress +# 安装为本地依赖项 +yarn add -D vuepress # 或 npm install -D vuepress -# create a docs directory +# 创建一个 docs 目录 mkdir docs -# create a markdown file +# 创建一个 markdown 文件 echo '# Hello VuePress' > docs/README.md ``` -::: warning -It is currently recommended to use [Yarn](https://yarnpkg.com/en/) instead of npm when installing VuePress into an existing project that has webpack 3.x as a dependency. Npm fails to generate the correct dependency tree in this case. +::: warning 警告 +当将 VuePress 安装到以 webpack 3.x 作为依赖项的已有项目中时，推荐使用[Yarn](https://yarnpkg.com/en/) 而不是 npm。因为在这种情况下，Npm 无法生成正确的依赖关系树。 ::: -Then, add some scripts to `package.json`: +然后，给 `package.json` 添加一些 scripts 脚本： ``` json { @@ -51,16 +51,16 @@ Then, add some scripts to `package.json`: } ``` -You can now start writing with: +你现在就可以开始编写文档了： ``` bash -yarn docs:dev # OR npm run docs:dev +yarn docs:dev # 或 npm run docs:dev ``` -To generate static assets, run: +要生成静态资源，请运行： ``` bash -yarn docs:build # Or npm run docs:build +yarn docs:build # 或 npm run docs:build ``` -By default the built files will be in `.vuepress/dist`, which can be configured via the `dest` field in `.vuepress/config.js`. The built files can be deployed to any static file server. See [Deployment Guide](./deploy.md) for guides on deploying to popular services. +默认情况下，构建的文件会位于 `.vuepress/dist` 中，该文件可以通过 `.vuepress/config.js` 中的 `dest` 字段进行配置。构建的文件可以部署到任何静态文件服务器。关于如何部署到一些常用服务，请参考 [部署指南](./deploy.md)。 diff --git a/docs/guide/i18n.md b/docs/guide/i18n.md index a051f2e9e7..b5348d6875 100644 --- a/docs/guide/i18n.md +++ b/docs/guide/i18n.md @@ -1,8 +1,8 @@ -# Internationalization +# 国际化支持(internationalization) -## Site Level i18n Config +## 网站级别的国际化配置(site level i18n config) -To leverage multi-language support in VuePress, you first need to use the following file structure: +想要在 VuePress 中支持多语言，首先你需要使用如下的文件结构： ``` docs @@ -17,32 +17,32 @@ docs    └─ README.md ``` -Then, specify the `locales` option in `.vuepress/config.js`: +然后，在 `.vuepress/config.js` 中指定 `locales` 选项： ``` js module.exports = { locales: { - // The key is the path for the locale to be nested under. - // As a special case, the default locale can use '/' as its path. + // 每个语言对象的键(key)，是语言的访问路径。 + // 然而，一种特例是将 '/' 作为默认语言的访问路径。 '/': { - lang: 'en-US', // this will be set as the lang attribute on + lang: 'en-US', // 这个值会被设置在 的 lang 属性上 title: 'VuePress', description: 'Vue-powered Static Site Generator' }, '/zh/': { lang: 'zh-CN', title: 'VuePress', - description: 'Vue 驱动的静态网站生成器' + description: 'Vue 驱动的静态网站生成工具' } } } ``` -If a locale does not have `title` or `description` VuePress will fallback to the root level values. You can omit the root level `title` and `description` as long as they are provided in each locale. +如果某个语言对象没有声明 `title` 或 `description`，VuePress 会尝试获取根语言对象上相应的值。如果每个语言对象都声明了 `title` 和 `description`，则可以省略根语言对象上的 `title` 和 `description`。 -## Default Theme i18n Config +## 默认主题的国际化配置(default theme i18n config) -The default theme also has built-in i18n support via `themeConfig.locales`, using the same `{ path: config }` format. Each locale can have its own [nav](../default-theme-config/README.md#navbar-links) and [sidebar](../default-theme-config/README.md#sidebar) config, in addition to a few other text values used across the site: +默认主题也内置国际化支持，可以通过 `themeConfig.locales` 来配置，与上面配置相同，也使用 `{ path: config }` 这种（路径+配置对象）格式。除了可以配置一些整个网站都会用到的文本，每个语言对象都有自己的 [导航栏](../default-theme-config/README.md#导航栏-navbar) 和 [侧边栏](../default-theme-config/README.md#侧边栏-sidebar)。 ``` js module.exports = { @@ -56,6 +56,13 @@ module.exports = { label: 'English', // text for the edit-on-github link editLinkText: 'Edit this page on GitHub', + // config for Service Worker + serviceWorker: { + updatePopup: { + message: "New content is available.", + buttonText: "Refresh" + } + }, // algolia docsearch options for current locale algolia: {}, nav: [ @@ -67,9 +74,18 @@ module.exports = { } }, '/zh/': { + // 语言下拉菜单的展示文本 selectText: '选择语言', + // 该语言在下拉菜单中的 label 标签 label: '简体中文', + // github 编辑链接的文字 editLinkText: '在 GitHub 上编辑此页', + serviceWorker: { + updatePopup: { + message: "发现新内容可用.", + buttonText: "刷新" + } + }, nav: [ { text: '嵌套', link: '/zh/nested/' } ], diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md index 459e4811db..bac34f0979 100644 --- a/docs/guide/markdown.md +++ b/docs/guide/markdown.md @@ -1,29 +1,29 @@ -# Markdown Extensions +# Markdown 扩展 -## Header Anchors +## 标题锚点(header anchors) -Headers automatically get anchor links applied. Rendering of anchors can be configured using the [`markdown.anchor`](../config/README.md#markdown-anchor) option. +标题会自动获取锚点链接。可以使用 [`markdown.anchor`](../config/README.md#markdown-anchor) 选项来配置锚点的渲染。 -## Links +## 链接(links) -### Internal Links +### 内部链接(internal links) -Inbound links ending in `.md` or `.html` are converted to `` for SPA navigation. +以 `.md` 或 `.html` 结尾的内部链接，会被转换为 ``，用于单页面应用程序(SPA)导航。 -Each sub-directory in your static site should contain a `README.md`. It will automatically be converted to `index.html`. +静态网站的每个子目录都应该包含一个 `README.md`。这个文件会自动转换为 `index.html`。 -::: tip -When writing the relative path to a directory's `index.html`, don't forget to close it off with a `/`, otherwise you will get a 404. For example, use `/config/` instead of `/config`. +::: tip 提示 +在编写「链接到某个目录下 `index.html`」的相对路径时，不要忘记在结尾用 `/` 闭合，否则你将得到一个 404。例如，使用 `/config/` 而不是 `/config`。 ::: -If you want to link to another markdown file within a directory, remember to: +如果你想要链接到另一个 markdown 文件，记得： -1. Append it with either `.html` or `.md` -2. Make sure the case matches since the path is case-sensitive +1. 在链接后面添加 `.html` 或 `.md` +2. 确保大小写对应正确，因为路径匹配是区分大小写的 -#### Example +#### 示例 -Given the following directory structure: +给定以下目录结构： ``` . @@ -39,25 +39,25 @@ Given the following directory structure: ``` ```md -[Home](/) -[foo](/foo/) -[foo heading anchor](/foo/#heading) -[foo - one](/foo/one.html) -[foo - two](/foo/two.md) +[Home](/) +[foo](/foo/) +[foo 标题锚点](/foo/#heading) +[foo - one](/foo/one.html) +[foo - two](/foo/two.md) ``` -### External Links +### 外部链接(external links) -Outbound links automatically gets `target="_blank" rel="noopener noreferrer"`: +外部链接会被自动地设置为 `target="_blank" rel="noopener noreferrer"`： - [vuejs.org](https://vuejs.org) - [VuePress on GitHub](https://github.com/vuejs/vuepress) -You can customize the attributes added to external links by setting [config.markdown.externalLinks](../config/README.md#markdown-externallinks). +你可以自定义通过配置 [config.markdown.externalLinks](../config/README.md#markdown-externallinks) 来自定义外部链接的特性。 ## Front Matter -[YAML front matter](https://jekyllrb.com/docs/frontmatter/) is supported out of the box: +提供开箱即用的 [YAML front matter](https://jekyllrb.com/docs/frontmatter/)： ``` yaml --- @@ -66,9 +66,9 @@ lang: en-US --- ``` -The data will be available to the rest of the page, plus all custom and theming components as `$page`. +数据在页面的其余部分也可以使用，包括所有自定义和主题组件，通过 `$page` 访问。 -`title` and `lang` will be automatically set on the current page. In addition you can specify extra meta tags to be injected: +`title` 和 `lang` 会在当前页面自动设置。另外，你可以指定额外的 meta 标签进行注入： ``` yaml --- @@ -80,11 +80,11 @@ meta: --- ``` -### Alternative Front Matter Formats +### 其他可选择的 Front Matter 格式 -In addition, VuePress also supports JSON or [TOML](https://github.com/toml-lang/toml) front matter. +除了 YAML，VuePress 也支持 JSON 或者 [TOML](https://github.com/toml-lang/toml) 格式的 front matter。 -JSON front matter needs to start and end in curly braces: +JSON front matter 需要使用花括号开头和结尾： ``` --- @@ -95,7 +95,7 @@ JSON front matter needs to start and end in curly braces: --- ``` -TOML front matter needs to be explicitly marked as TOML: +TOML front matter 需要显式地标注为 TOML： ``` ---toml @@ -104,9 +104,9 @@ lang = "en-US" --- ``` -## GitHub-Style Tables +## GitHub 风格的表格 -**Input** +**输入** ``` | Tables | Are | Cool | @@ -116,7 +116,7 @@ lang = "en-US" | zebra stripes | are neat | $1 | ``` -**Output** +**输出** | Tables | Are | Cool | | ------------- |:-------------:| -----:| @@ -126,35 +126,35 @@ lang = "en-US" ## Emoji :tada: -**Input** +**输入** ``` :tada: :100: ``` -**Output** +**输出** :tada: :100: -A list of all emojis available can be found [here](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.json). +在[这里](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.json)可以找到所有可用的 emojis 列表。 -## Table of Contents +## 目录(table of contents) -**Input** +**输入** ``` [[toc]] ``` -**Output** +**输出** [[toc]] -Rendering of TOC can be configured using the [`markdown.toc`](../config/README.md#markdown-toc) option. +可以使用 [`markdown.toc`](../config/README.md#markdown-toc) 选项，来配置目录(table of contents - TOC)的渲染。 -## Custom Containers +## 自定义容器(custom containers) -**Input** +**输入** ``` ::: tip @@ -170,7 +170,7 @@ This is a dangerous warning ::: ``` -**Output** +**输出** ::: tip This is a tip @@ -184,7 +184,7 @@ This is a warning This is a dangerous thing ::: -You can also customize the title of the block: +你还可以自定义块的标题： ``` ::: danger STOP @@ -196,9 +196,9 @@ Danger zone, do not proceed Danger zone, do not proceed ::: -## Line Highlighting in Code Blocks +## 在代码块中高亮显示行(line highlighting in code blocks) -**Input** +**输入** ```` ``` js{4} @@ -212,7 +212,7 @@ export default { ``` ```` -**Output** +**输出** ``` js{4} export default { @@ -224,9 +224,9 @@ export default { } ``` -## Line Numbers +## 行号 -You can enable line numbers for each code blocks via config: +你可以通过配置给每个代码块启用行号： ``` js module.exports = { @@ -238,7 +238,7 @@ module.exports = { -- Demo: +- 示例: @@ -268,48 +268,48 @@ module.exports = { } -## Import Code Snippets +## 导入代码片段 -You can import code snippets from existing files via following syntax: +你能够通过下面的语法从已有文件里导入代码片段： ``` md <<< @/filepath ``` -It also supports [line highlighting](#line-highlighting-in-code-blocks): +它也支持[行高亮](#line-highlighting-in-code-blocks): ``` md <<< @/filepath{highlightLines} ``` -**Input** +**输入** ``` md <<< @/test/markdown/fragments/snippet.js{2} ``` -**Output** +**输出** <<< @/test/markdown/fragments/snippet.js{2} ::: tip - Since the import of the code snippets will be executed before webpack compilation, you can't use the path alias in webpack. The default value of `@` is `process.cwd()`. +由于导入的代码片段会在 webpack 编译之前执行，因此你无法在 webpack 中使用路径别名。`@` 的默认值是 `process.cwd（）` 。 ::: -## Advanced Configuration +## 高级配置(advanced configuration) -VuePress uses [markdown-it](https://github.com/markdown-it/markdown-it) as the markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the `markdown-it` instance using the `markdown` option in `.vuepress/config.js`: +VuePress 使用 [markdown-it](https://github.com/markdown-it/markdown-it)作为 markdwon 渲染器。上面的许多扩展都是通过定制插件实现的。你可以使用 `.vuepress/config.js` 中的 `markdown` 选项进一步自定义 `markdown-it` 实例： ``` js module.exports = { markdown: { - // options for markdown-it-anchor + // markdown-it-anchor 的选项 anchor: { permalink: false }, - // options for markdown-it-toc + // markdown-it-toc 的选项 toc: { includeLevel: [1, 2] }, config: md => { - // use more markdown-it plugins! + // 使用更多 markdown-it 插件！ md.use(require('markdown-it-xxx')) } } diff --git a/docs/guide/using-vue.md b/docs/guide/using-vue.md index 13dba07530..355e3c4294 100644 --- a/docs/guide/using-vue.md +++ b/docs/guide/using-vue.md @@ -1,10 +1,10 @@ -# Using Vue in Markdown +# 在 Markdown 中使用 Vue -## Browser API Access Restrictions +## 浏览器 API 访问限制 -Because VuePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the [universal code requirements](https://ssr.vuejs.org/en/universal.html). In short, make sure to only access Browser / DOM APIs in `beforeMount` or `mounted` hooks. +由于 VuePress 应用程序在生成静态构建文件时，会通过 Node.js 进行服务器端渲染，所以任何 Vue 用法都必须符合 [编写通用代码](https://ssr.vuejs.org/zh/guide/universal.html) 的要求。简而言之，确保只在 `beforeMounted` 或 `mounted` 钩子函数中访问 浏览器特定 API / DOM API。 -If you are using or demoing components that are not SSR friendly (for example containing custom directives), you can wrap them inside the built-in `` component: +如果你正在使用或展示一个对于 SSR 不友好的组件（比如说包含了自定义指令），则可以将它们包装在内置的 `` 组件中： ``` md @@ -12,7 +12,7 @@ If you are using or demoing components that are not SSR friendly (for example co ``` -Note this does not fix components or libraries that access Browser APIs **on import** - in order to use code that assumes a browser environment on import, you need to dynamically import them in proper lifecycle hooks: +请注意，这无法解决一些组件或库在**静态导入(import)**时就试图访问浏览器 API 的问题 - 为了使用在导入时使用浏览器环境的代码，你需要在合适的生命周期钩子函数中，动态导入(dynamically import)它们： ``` vue ``` -## Templating +## 模板(templating) -### Interpolation +### 插值 -Each markdown file is first compiled into HTML and then passed on as a Vue component to `vue-loader`. This means you can use Vue-style interpolation in text: +每个 markdown 文件首先被编译成 HTML，然后作为 Vue 组件传递给 `vue-loader`。这意味着你可以在文本中使用 Vue 风格的插值表达式： -**Input** +**输入** ``` md {{ 1 + 1 }} ``` -**Output** +**输出** -
{{ 1 + 1 }}
+
{{ 1 + 1 }}
-### Directives +### 指令 -Directives also work: +也可以运行指令： -**Input** +**输入** ``` md {{ i }} ``` -**Output** +**输出** -
{{ i }}
+
{{ i }}
-### Access to Site & Page Data +### 访问网站和页面数据 -The compiled component does not have any private data but does have access to the [site metadata](./custom-themes.md#site-and-page-metadata). For example: +编译后的组件没有任何私有数据，但是我们可以访问到 [网站元数据](./custom-themes.md#网站和网页元数据-site-and-page-metadata)。例如： -**Input** +**输入** ``` md {{ $page }} ``` -**Output** +**输出** ``` json { @@ -76,11 +76,11 @@ The compiled component does not have any private data but does have access to th } ``` -## Escaping +## 转义(escaping) -By default, fenced code blocks are automatically wrapped with `v-pre`. If you want to display raw mustaches or Vue-specific syntax inside inline code snippets or plain text, you need to wrap a paragraph with the `v-pre` custom container: +默认情况下，花括号代码块(fenced code blocks)会自动用 `v-pre` 包装。如果要在内联代码片段或纯文本内显示原始插值或特定于 Vue 的语法，则需要把段落包裹在 `v-pre` 自定义容器中： -**Input** +**输入** ``` md ::: v-pre @@ -88,15 +88,15 @@ By default, fenced code blocks are automatically wrapped with `v-pre`. If you wa ::: ``` -**Output** +**输出** ::: v-pre `{{ This will be displayed as-is }}` ::: -## Using Components +## 使用组件（Using Components） -Any `*.vue` files found in `.vuepress/components` are automatically registered as [global](https://vuejs.org/v2/guide/components-registration.html#Global-Registration), [async](https://vuejs.org/v2/guide/components-dynamic-async.html#Async-Components) components. For example: +`.vuepress/components` 中的所有 `*.vue` 文件都会自动注册为 [全局(global)](https://vuejs.org/v2/guide/components-registration.html#Global-Registration)[异步(async)](https://vuejs.org/v2/guide/components-dynamic-async.html#Async-Components) 组件。例如： ``` . @@ -108,7 +108,7 @@ Any `*.vue` files found in `.vuepress/components` are automatically registered a         └─ Bar.vue ``` -Inside any markdown file you can then directly use the components (names are inferred from filenames): +在所有 markdown 文件中，你都可以直接使用这些组件（其名称(name)是从文件名推断出的）： ``` md @@ -122,19 +122,34 @@ Inside any markdown file you can then directly use the components (names are inf -::: warning IMPORTANT -Make sure a custom component's name either contains a hyphen or is in PascalCase. Otherwise it will be treated as an inline element and wrapped inside a `

` tag, which will lead to hydration mismatch because `

` does not allow block elements to be placed inside it. +::: warning 重要 +确保自定义组件的名称，是由连字符(hyphen)拼接，或者遵循帕斯卡命名(PascalCase)。否则，它将被视为内联元素，然后被包裹在一个 `

` 标签内，这将导致 hydration 无法匹配，这是因为 `

` 中不允许放置块元素。（译注：查看 [SSR 客户端激活(client-side hydration)](https://ssr.vuejs.org/zh/guide/hydration.html)） ::: -### Using Pre-processors +## 在标题中使用 Vue 组件 + +你可以在标题中使用 Vue 组件，但是请注意以下两种方式的不同： + +| Markdown | 输出的 HTML | 解析后的标题 | +|--------|-------------|----------------| +| 

 # text <Tag/>
| `

text

` | `text` | +| 
 # text \`<Tag/>\`
| `

text <Tag/>

` | `text ` | + +被 `` 包装的 HTML 将按原样显示，只有未被包装的 HTML 才会被 Vue 解析。 + +::: tip +输出的 HTML 由 [markdown-it](https://github.com/markdown-it/markdown-it) 完成。而解析后的标题由 VuePress 完成，用于[侧边栏](../default-theme-config/README.md#侧边栏)以及文档的标题。 +::: + +## 使用预处理器 + +VuePress 已经为如下预处理器内置了相关的 webpack 配置：`sass`, `scss`, `less`, `stylus` 和 `pug`。要使用它们，你只需要在项目中安装对应的依赖即可。例如，要使用 `sass`，直接在项目中安装： -VuePress has built-in webpack config for the following pre-processors: `sass`, `scss`, `less`, `stylus` and `pug`. All you need to do is installing the corresponding dependencies. For example, to enable `sass`, install the following in your project: - ``` bash yarn add -D sass-loader node-sass ``` -Now you can use the following in markdown and theme components: +接着，你就可以在 markdown 或者主题组件中使用如下代码： ``` vue ``` -Using `