mirror of
https://gitee.com/docsifyjs/docsify.git
synced 2024-12-02 03:59:19 +08:00
Merge pull request #1618 from johnjago/improve-wording-guide
docs: improve English wording (Guide)
This commit is contained in:
Joe Pea
GitHub
commit
9d3f50b1df
@ -20,8 +20,8 @@
|
||||
- [Helpers](helpers.md)
|
||||
- [Vue compatibility](vue.md)
|
||||
- [CDN](cdn.md)
|
||||
- [Offline Mode(PWA)](pwa.md)
|
||||
- [Server-Side Rendering(SSR)](ssr.md)
|
||||
- [Offline Mode (PWA)](pwa.md)
|
||||
- [Server-Side Rendering (SSR)](ssr.md)
|
||||
- [Embed Files](embed-files.md)
|
||||
|
||||
- [Awesome docsify](awesome.md)
|
||||
|
||||
@ -4,22 +4,22 @@ Similar to [GitBook](https://www.gitbook.com), you can deploy files to GitHub Pa
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
There're three places to populate your docs for your Github repository:
|
||||
There are three places to populate your docs for your GitHub repository:
|
||||
|
||||
- `docs/` folder
|
||||
- master branch
|
||||
- gh-pages branch
|
||||
|
||||
It is recommended that you save your files to the `./docs` subfolder of the `master` branch of your repository. Then select `master branch /docs folder` as your Github Pages source in your repositories' settings page.
|
||||
It is recommended that you save your files to the `./docs` subfolder of the `master` branch of your repository. Then select `master branch /docs folder` as your GitHub Pages source in your repository's settings page.
|
||||
|
||||
|
||||
|
||||
|
||||
!> You can also save files in the root directory and select `master branch`.
|
||||
You'll need to place a `.nojekyll` file in the deploy location (such as `/docs` or the gh-pages branch)
|
||||
|
||||
## GitLab Pages
|
||||
|
||||
If you are deploying your master branch, include `.gitlab-ci.yml` with the following script:
|
||||
If you are deploying your master branch, create a `.gitlab-ci.yml` with the following script:
|
||||
|
||||
?> The `.public` workaround is so `cp` doesn't also copy `public/` to itself in an infinite loop.
|
||||
|
||||
@ -43,9 +43,9 @@ pages:
|
||||
|
||||
!> You'll need to install the Firebase CLI using `npm i -g firebase-tools` after signing into the [Firebase Console](https://console.firebase.google.com) using a Google Account.
|
||||
|
||||
Using Terminal determine and navigate to the directory for your Firebase Project - this could be `~/Projects/Docs` etc. From there, run `firebase init`, choosing `Hosting` from the menu (use **space** to select, **arrow keys** to change options and **enter** to confirm). Follow the setup instructions.
|
||||
Using a terminal, determine and navigate to the directory for your Firebase Project. This could be `~/Projects/Docs`, etc. From there, run `firebase init` and choose `Hosting` from the menu (use **space** to select, **arrow keys** to change options and **enter** to confirm). Follow the setup instructions.
|
||||
|
||||
You should have your `firebase.json` file looking similar to this (I changed the deployment directory from `public` to `site`):
|
||||
Your `firebase.json` file should look similar to this (I changed the deployment directory from `public` to `site`):
|
||||
|
||||
```json
|
||||
{
|
||||
@ -56,11 +56,11 @@ You should have your `firebase.json` file looking similar to this (I changed the
|
||||
}
|
||||
```
|
||||
|
||||
Once finished, build the starting template by running `docsify init ./site` (replacing site with the deployment directory you determined when running `firebase init` - public by default). Add/edit the documentation, then run `firebase deploy` from the base project directory.
|
||||
Once finished, build the starting template by running `docsify init ./site` (replacing site with the deployment directory you determined when running `firebase init` - public by default). Add/edit the documentation, then run `firebase deploy` from the root project directory.
|
||||
|
||||
## VPS
|
||||
|
||||
Try following nginx config.
|
||||
Use the following nginx config.
|
||||
|
||||
```nginx
|
||||
server {
|
||||
@ -78,11 +78,11 @@ server {
|
||||
|
||||
1. Login to your [Netlify](https://www.netlify.com/) account.
|
||||
2. In the [dashboard](https://app.netlify.com/) page, click **New site from Git**.
|
||||
3. Choose a repository where you store your docs, leave the **Build Command** area blank, fill in the Publish directory area with the directory of your `index.html`, for example it should be docs if you populated it at `docs/index.html`.
|
||||
3. Choose a repository where you store your docs, leave the **Build Command** area blank, and fill in the Publish directory area with the directory of your `index.html`. For example, it should be docs if you populated it at `docs/index.html`.
|
||||
|
||||
### HTML5 router
|
||||
|
||||
When using the HTML5 router, you need to set up redirect rules that redirect all requests to your `index.html`, it's pretty simple when you're using Netlify, create a file named `_redirects` in the docs directory, add this snippet to the file and you're all set:
|
||||
When using the HTML5 router, you need to set up redirect rules that redirect all requests to your `index.html`. It's pretty simple when you're using Netlify. Just create a file named `_redirects` in the docs directory, add this snippet to the file, and you're all set:
|
||||
|
||||
```sh
|
||||
/* /index.html 200
|
||||
@ -117,7 +117,7 @@ version: 0.1
|
||||
frontend:
|
||||
phases:
|
||||
build:
|
||||
commands:
|
||||
commands:
|
||||
- echo "Nothing to build"
|
||||
artifacts:
|
||||
baseDirectory: /docs
|
||||
@ -128,20 +128,20 @@ frontend:
|
||||
|
||||
```
|
||||
|
||||
6. Add the following Redirect rules in their displayed order. Note that the second record is a PNG image where you can change it with any image format you are using.
|
||||
6. Add the following Redirect rules in their displayed order. Note that the second record is a PNG image where you can change it with any image format you are using.
|
||||
|
||||
| Source address | Target address | Type |
|
||||
|----------------|----------------|---------------|
|
||||
| /<*>.md | /<*>.md | 200 (Rewrite) |
|
||||
| /<*>.png | /<*>.png | 200 (Rewrite) |
|
||||
| /<*> | /index.html | 200 (Rewrite) |
|
||||
| /<*> | /index.html | 200 (Rewrite) |
|
||||
|
||||
|
||||
## Docker
|
||||
|
||||
- Create docsify files
|
||||
- Create docsify files
|
||||
|
||||
You need prepare the initial files instead of making in container.
|
||||
You need prepare the initial files instead of making them inside the container.
|
||||
See the [Quickstart](https://docsify.js.org/#/quickstart) section for instructions on how to create these files manually or using [docsify-cli](https://github.com/docsifyjs/docsify-cli).
|
||||
|
||||
```sh
|
||||
@ -149,7 +149,7 @@ frontend:
|
||||
README.md
|
||||
```
|
||||
|
||||
- Create dockerfile
|
||||
- Create Dockerfile
|
||||
|
||||
```Dockerfile
|
||||
FROM node:latest
|
||||
@ -158,10 +158,10 @@ frontend:
|
||||
RUN npm install -g docsify-cli@latest
|
||||
EXPOSE 3000/tcp
|
||||
ENTRYPOINT docsify serve .
|
||||
|
||||
|
||||
```
|
||||
|
||||
So, current directory structure should be this:
|
||||
The current directory structure should be this:
|
||||
|
||||
```sh
|
||||
index.html
|
||||
@ -178,6 +178,6 @@ frontend:
|
||||
- Run docker image
|
||||
|
||||
```sh
|
||||
docker run -itp 3000:3000 --name=docsify -v $(pwd):/docs docsify/demo
|
||||
docker run -itp 3000:3000 --name=docsify -v $(pwd):/docs docsify/demo
|
||||
```
|
||||
|
||||
|
||||
@ -10,13 +10,13 @@ For example, here is an embedded Markdown file. You only need to do this:
|
||||
[filename](_media/example.md ':include')
|
||||
```
|
||||
|
||||
Then the content of `example.md` will be displayed directly here;
|
||||
Then the content of `example.md` will be displayed directly here:
|
||||
|
||||
[filename](_media/example.md ':include')
|
||||
|
||||
You can check the original content for [example.md](_media/example.md ':ignore').
|
||||
|
||||
Normally, this will compiled into a link, but in docsify, if you add `:include` it will be embedded. You can use single or double quotation marks around as you like.
|
||||
Normally, this will be compiled into a link, but in docsify, if you add `:include` it will be embedded. You can use single or double quotation marks around as you like.
|
||||
|
||||
External links can be used too - just replace the target. If you want to use a gist URL, see [Embed a gist](#embed-a-gist) section.
|
||||
|
||||
@ -73,7 +73,7 @@ Example:
|
||||
|
||||
If you embed the file as `iframe`, `audio` and `video`, then you may need to set the attributes of these tags.
|
||||
|
||||
?> Note, for the `audio` and `video` types, docsify adds the `controls` attribute by default. When you want add more attributes, the `controls` attribute need to be added manually if need be.
|
||||
?> Note, for the `audio` and `video` types, docsify adds the `controls` attribute by default. When you want add more attributes, the `controls` attribute need to be added manually if need be.
|
||||
```md
|
||||
[filename](_media/example.mp4 ':include :type=video controls width=100%')
|
||||
```
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
docsify extends Markdown syntax to make your documents more readable.
|
||||
|
||||
> Note: For the special code syntax cases, you'd better put them within a code backticks to avoid any conflicting from configurations or emojis.
|
||||
> Note: For the special code syntax cases, it's better to put them within code backticks to avoid any conflict from configurations or emojis.
|
||||
|
||||
## Important content
|
||||
|
||||
@ -30,13 +30,13 @@ are rendered as:
|
||||
|
||||
## Ignore to compile link
|
||||
|
||||
Some time we will put some other relative path to the link, you have to need to tell docsify you don't need to compile this link. For example
|
||||
Sometimes we will use some other relative path for the link, and we have to tell docsify that we don't need to compile this link. For example:
|
||||
|
||||
```md
|
||||
[link](/demo/)
|
||||
```
|
||||
|
||||
It will be compiled to `<a href="/#/demo/">link</a>` and will be loaded `/demo/README.md`. Maybe you want to jump to `/demo/index.html`.
|
||||
It will be compiled to `<a href="/#/demo/">link</a>` and will load `/demo/README.md`. Maybe you want to jump to `/demo/index.html`.
|
||||
|
||||
Now you can do that
|
||||
|
||||
@ -44,7 +44,7 @@ Now you can do that
|
||||
[link](/demo/ ':ignore')
|
||||
```
|
||||
|
||||
You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set title for link.
|
||||
You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set the title for the link.
|
||||
|
||||
```md
|
||||
[link](/demo/ ':ignore title')
|
||||
@ -67,13 +67,13 @@ You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set ti
|
||||
|
||||
## Cross-Origin link
|
||||
|
||||
Only when you both set the `routerMode: 'history'` and `externalLinkTarget: '_self'`, you need add this configuration for those Cross-Origin links.
|
||||
Only when you set both the `routerMode: 'history'` and `externalLinkTarget: '_self'`, you need to add this configuration for those Cross-Origin links.
|
||||
|
||||
```md
|
||||
[example.com](https://example.com/ ':crossorgin')
|
||||
```
|
||||
|
||||
## Github Task Lists
|
||||
## GitHub Task Lists
|
||||
|
||||
```md
|
||||
- [ ] foo
|
||||
@ -150,7 +150,7 @@ This is useful for rendering markdown content in the details element.
|
||||
|
||||
</details>
|
||||
|
||||
Or markdown content can be wrapped in html tag.
|
||||
Markdown content can also be wrapped in html tags.
|
||||
|
||||
```markdown
|
||||
<div style='color: red'>
|
||||
|
||||
@ -2,11 +2,11 @@
|
||||
|
||||
[Progressive Web Apps](https://developers.google.com/web/progressive-web-apps/) (PWA) are experiences that combine the best of the web with the best of apps. We can enhance our website with service workers to work **offline** or on low-quality networks.
|
||||
|
||||
It is also very easy to use it.
|
||||
It is also very easy to use.
|
||||
|
||||
## Create serviceWorker
|
||||
|
||||
Create a `sw.js` file in your documents root directory and copy the following code:
|
||||
Create a `sw.js` file in your project's root directory and copy the following code:
|
||||
|
||||
*sw.js*
|
||||
|
||||
@ -98,7 +98,7 @@ self.addEventListener('fetch', event => {
|
||||
|
||||
## Register
|
||||
|
||||
Now, register it in your `index.html`. It only works on some modern browsers, so we need to judge:
|
||||
Now, register it in your `index.html`. It only works on some modern browsers, so we need to check:
|
||||
|
||||
*index.html*
|
||||
|
||||
@ -112,4 +112,4 @@ Now, register it in your `index.html`. It only works on some modern browsers, so
|
||||
|
||||
## Enjoy it
|
||||
|
||||
Release your website and start experiencing magical offline feature. :ghost: You can turn off Wi-Fi and refresh the current site to experience it.
|
||||
Release your website and start experiencing the magical offline feature. :ghost: You can turn off Wi-Fi and refresh the current site to experience it.
|
||||
|
||||
@ -16,7 +16,7 @@ Install `now` and `docsify-cli` in your project.
|
||||
npm i now docsify-cli -D
|
||||
```
|
||||
|
||||
Edit `package.json`. If the documentation in `./docs` subdirectory.
|
||||
Edit `package.json`. The below assumes the documentation is in the `./docs` subdirectory.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -42,7 +42,7 @@ Edit `package.json`. If the documentation in `./docs` subdirectory.
|
||||
|
||||
!> The `basePath` just like webpack `publicPath`. We can use local or remote files.
|
||||
|
||||
We can preview in the local to see if it works.
|
||||
We can preview the local site to see if it works.
|
||||
|
||||
```bash
|
||||
npm start
|
||||
@ -56,11 +56,11 @@ Publish it!
|
||||
now -p
|
||||
```
|
||||
|
||||
Now, You have a support for SSR the docs site.
|
||||
Now, you have support for SSR.
|
||||
|
||||
## Custom template
|
||||
|
||||
You can provide a template for entire page's HTML. such as
|
||||
You can provide a template for an entire page's HTML, such as
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Vue compatibility
|
||||
|
||||
Docsify allows Vue content to be added directly to you markdown pages. This can greatly simplify working with data and adding reactivity to your site.
|
||||
Docsify allows Vue content to be added directly to your markdown pages. This can greatly simplify working with data and adding reactivity to your site.
|
||||
|
||||
To get started, add Vue [2.x](https://vuejs.org) or [3.x](https://v3.vuejs.org) to your `index.html` file. Choose the production version for your live site or the development version for helpful console warnings and [Vue.js devtools](https://github.com/vuejs/vue-devtools) support.
|
||||
|
||||
|
||||
@ -9,4 +9,4 @@ exports[`Docs Site coverpage renders and is unchanged 1`] = `
|
||||
|
||||
exports[`Docs Site navbar renders and is unchanged 1`] = `"<nav class=\\"app-nav no-badge\\"><ul><li>Translations<ul><li><a href=\\"#/\\" title=\\"undefined\\" class=\\"active\\"><img class=\\"emoji\\" src=\\"https://github.githubassets.com/images/icons/emoji/uk.png\\" alt=\\"uk\\"> English</a></li><li><a href=\\"#/zh-cn/\\" title=\\"undefined\\"><img class=\\"emoji\\" src=\\"https://github.githubassets.com/images/icons/emoji/cn.png\\" alt=\\"cn\\"> 中文</a></li><li><a href=\\"#/de-de/\\" title=\\"undefined\\"><img class=\\"emoji\\" src=\\"https://github.githubassets.com/images/icons/emoji/de.png\\" alt=\\"de\\"> Deutsch</a></li><li><a href=\\"#/es/\\" title=\\"undefined\\"><img class=\\"emoji\\" src=\\"https://github.githubassets.com/images/icons/emoji/es.png\\" alt=\\"es\\"> Español</a></li><li><a href=\\"#/ru-ru/\\" title=\\"undefined\\"><img class=\\"emoji\\" src=\\"https://github.githubassets.com/images/icons/emoji/ru.png\\" alt=\\"ru\\"> Русский</a></li></ul></li></ul></nav>"`;
|
||||
|
||||
exports[`Docs Site sidebar renders and is unchanged 1`] = `"<aside class=\\"sidebar\\"><div class=\\"sidebar-nav\\"><ul><li><p>Getting started</p><ul><li><a href=\\"#/quickstart\\" title=\\"undefined\\">Quick start</a></li><li><a href=\\"#/more-pages\\" title=\\"undefined\\">Writing more pages</a></li><li><a href=\\"#/custom-navbar\\" title=\\"undefined\\">Custom navbar</a></li><li><a href=\\"#/cover\\" title=\\"undefined\\">Cover page</a></li></ul></li><li><p>Customization</p><ul><li><a href=\\"#/configuration\\" title=\\"undefined\\">Configuration</a></li><li><a href=\\"#/themes\\" title=\\"undefined\\">Themes</a></li><li><a href=\\"#/plugins\\" title=\\"undefined\\">List of Plugins</a></li><li><a href=\\"#/write-a-plugin\\" title=\\"undefined\\">Write a Plugin</a></li><li><a href=\\"#/markdown\\" title=\\"undefined\\">Markdown configuration</a></li><li><a href=\\"#/language-highlight\\" title=\\"undefined\\">Language highlighting</a></li></ul></li><li><p>Guide</p><ul><li><a href=\\"#/deploy\\" title=\\"undefined\\">Deploy</a></li><li><a href=\\"#/helpers\\" title=\\"undefined\\">Helpers</a></li><li><a href=\\"#/vue\\" title=\\"undefined\\">Vue compatibility</a></li><li><a href=\\"#/cdn\\" title=\\"undefined\\">CDN</a></li><li><a href=\\"#/pwa\\" title=\\"undefined\\">Offline Mode(PWA)</a></li><li><a href=\\"#/ssr\\" title=\\"undefined\\">Server-Side Rendering(SSR)</a></li><li><a href=\\"#/embed-files\\" title=\\"undefined\\">Embed Files</a></li></ul></li><li><p><a href=\\"#/awesome\\" title=\\"undefined\\">Awesome docsify</a></p></li><li><p><a href=\\"#/changelog\\" title=\\"undefined\\">Changelog</a></p></li></ul></div></aside>"`;
|
||||
exports[`Docs Site sidebar renders and is unchanged 1`] = `"<aside class=\\"sidebar\\"><div class=\\"sidebar-nav\\"><ul><li><p>Getting started</p><ul><li><a href=\\"#/quickstart\\" title=\\"undefined\\">Quick start</a></li><li><a href=\\"#/more-pages\\" title=\\"undefined\\">Writing more pages</a></li><li><a href=\\"#/custom-navbar\\" title=\\"undefined\\">Custom navbar</a></li><li><a href=\\"#/cover\\" title=\\"undefined\\">Cover page</a></li></ul></li><li><p>Customization</p><ul><li><a href=\\"#/configuration\\" title=\\"undefined\\">Configuration</a></li><li><a href=\\"#/themes\\" title=\\"undefined\\">Themes</a></li><li><a href=\\"#/plugins\\" title=\\"undefined\\">List of Plugins</a></li><li><a href=\\"#/write-a-plugin\\" title=\\"undefined\\">Write a Plugin</a></li><li><a href=\\"#/markdown\\" title=\\"undefined\\">Markdown configuration</a></li><li><a href=\\"#/language-highlight\\" title=\\"undefined\\">Language highlighting</a></li></ul></li><li><p>Guide</p><ul><li><a href=\\"#/deploy\\" title=\\"undefined\\">Deploy</a></li><li><a href=\\"#/helpers\\" title=\\"undefined\\">Helpers</a></li><li><a href=\\"#/vue\\" title=\\"undefined\\">Vue compatibility</a></li><li><a href=\\"#/cdn\\" title=\\"undefined\\">CDN</a></li><li><a href=\\"#/pwa\\" title=\\"undefined\\">Offline Mode (PWA)</a></li><li><a href=\\"#/ssr\\" title=\\"undefined\\">Server-Side Rendering (SSR)</a></li><li><a href=\\"#/embed-files\\" title=\\"undefined\\">Embed Files</a></li></ul></li><li><p><a href=\\"#/awesome\\" title=\\"undefined\\">Awesome docsify</a></p></li><li><p><a href=\\"#/changelog\\" title=\\"undefined\\">Changelog</a></p></li></ul></div></aside>"`;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user