diff --git a/CHANGELOG.md b/CHANGELOG.md index e1f839ea..9a2915e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,13 +5,14 @@ #### Features - feat(src): add alias feature -- update all docs -- dynamic title +- update all documents +- feat(src): dynamic title +- feat(hook): support custom plugin #### Bug fixes - fix(event): `auto2top` has no effect on a FF mobile browser, fixed #67 - fix: sidebar style - +- fix(render): fix render link ### 2.2.1 diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 1c87b241..44f33bca 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,4 +1,4 @@ -- Basic +- Get started - [Quick start](/quickstart) - [Writing more pages](/more-pages) - [Custom nav](/custom-navbar) diff --git a/docs/cdn.md b/docs/cdn.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/cover.md b/docs/cover.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/custom-navbar.md b/docs/custom-navbar.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/deploy.md b/docs/deploy.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/helpers.md b/docs/helpers.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/language-highlight.md b/docs/language-highlight.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/markdown.md b/docs/markdown.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/more-pages.md b/docs/more-pages.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 00000000..5297e733 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,3 @@ +# Quick start + +Remme \ No newline at end of file diff --git a/docs/themes.md b/docs/themes.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/vue.md b/docs/vue.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/zh-cn.md b/docs/zh-cn.md deleted file mode 100644 index d6481e14..00000000 --- a/docs/zh-cn.md +++ /dev/null @@ -1,532 +0,0 @@ - -## 特性 -- 无需构建，写完 markdown 直接发布 -- 支持自定义主题 -- 容易使用并且轻量 (~12kb gzipped) - -## 快速上手 - -### 创建项目 -新建一个空项目，接着创建一个 `docs` 目录并进入到 docs 目录下 -```bash -mkdir my-project && cd my-project -mkdir docs && cd docs -``` - -### 创建入口文件 -创建一个 `index.html` 文件，内容为 -```html - - - - - - - -
- - - -``` - -新建 `README.md` 文件，作为主页面 - -``` -# Title - -## balabala -``` - -### 部署！ -将项目 `push` 到 GitHub 仓库后到设置页面开启 **GitHub Pages** 功能，选择 `docs/` 选项 -![image](https://cloud.githubusercontent.com/assets/7565692/20639058/e65e6d22-b3f3-11e6-9b8b-6309c89826f2.png) - -## 命令行工具 - -方便快速创建文档目录，会读取项目的 `package.json` 里的选项作为 docsify 的配置，支持本地预览。 - -### 安装 -```bash -npm i docsify-cli -g -``` - -### 初始化文档 - -默认初始化在当前目录，推荐将文档放在 `docs` 目录下 -```bash -docsify init docs -``` - -### 启动本地服务 -启动一个 server 方便预览，打开 http://localhost:3000 -```bash -docsify serve docs -``` - -更多选项参考 [docsify-cli](https://github.com/QingWei-Li/docsify-cli) - - -## 更多功能 - -### 主题 -目前提供 vue.css 和 buble.css，直接修改 `index.html` 里的 cdn 地址即可 -```html - - -``` - -压缩版 - -```html - - -``` - -### 多页面 -`README.md` 作为主页面，如果需要其他页面，直接在文档目录下创建对应的 `*.md` 文件，例如创建一个 `guide.md` 那么对应的路由就是 `/#/guide`。 - -### 导航 -导航需要自己写在 `index.html` 文件里，效果参考本文档 - -```html - -``` - - - -### CDN -- UNPKG [https://unpkg.com/docsify/](https://unpkg.com/docsify/) -- jsDelivr [http://www.jsdelivr.com/projects/docsify](http://www.jsdelivr.com/projects/docsify) - -### 封面 - -只需要写几行简单的 markdown 就可以拥有一页精致的封面，通过添加 `data-coverpage` 属性，并创建 `_coverpage.md`，按照下面的格式书写即可。 - -```markdown -![logo](_media/icon.svg) - -# docsify 1.2.0 - -> A magical documentation site generator. - -- Simple and lightweight (~12kb gzipped) -- Multiple themes -- Not build static html files - - -[GitHub](https://github.com/QingWei-Li/docsify/) -[Get Started](#quick-start) -``` - - -#### 自定义封面背景 -默认的背景是随机生成的，你可以自定义背景色或者背景图片。只需要在文档末尾用添加图片的 Markdown 语法 - -```markdown -# docsify 1.2.0 - -> xxx - -[GitHub](https://github.com/QingWei-Li/docsify/) -[Get Started](#quick-start) - - -![](_media/bg.png) - -![color](#f0f0f0) -``` - -### 自定义 Markdown parser - -默认使用 [marked](https://github.com/chjj/marked) 处理 markdown 部分，你可以修改默认配置 - -```js -window.$docsify = { - markdown: { - smartypants: true - } -} -``` - -甚至可以完全定制化 - -```js -window.$docsify = { - markdown: function(marked) { - // ... - - return marked - } -} -``` - -### 文档助手 -#### 内置「提示」语法 - -`!>`后面接内容，会渲染成带 tip 类名的段落。 - -```markdown -!> 提示信息，**支持其他 markdown 语法** -``` - -将被渲染成 - -```html -

提示信息支持其他 markdown 语法

-``` - -效果 - -!> 适合显示醒目的内容 - -#### 内置「警示」语法 - -`?>`后面接内容，会渲染成带 warn 类名的段落。 - -```markdown -?> 警示内容样式 -``` - -效果 - -?> 警示内容样式 - -### 结合 Vue - -`index.html` 内引入 Vue 后，可以在文档里直接写 Vue 语法。默认会自己初始化一个 Vue 示例，当然我们也可以手动初始化一个实例。 - -index.html -```html - - -``` - -```markdown - -``` - -手动初始化示例 - -```markdown -
- -

Hello, {{ msg }}

-
- - -``` - -## 配置参数 - -你可以通过在标签上添加属性的方式，或者给 `window.$docsify` 传配置信息。 - -### repo -参考本文档的右上角的 GitHub 图标，如果要开启的话，将 `index.html` 里的 script 改成 - -```html - -``` - - -```js -window.$docsify = { - repo: 'your/repo' -} -``` - -### max-level -目录最大展开层级，默认值为 6 - -```html - -``` - - -```js -window.$docsify = { - maxLevel: 6 -} -``` - -### el -替换节点元素，默认为 `#app` -```html - -``` - - -```js -window.$docsify = { - el: '#app' -} -``` - -### load-sidebar - -读取侧边栏配置文件，如果配置，默认加载当前目录下的 `_sidebar.md`。如果文件不存在，会显示 TOC 作为侧边栏内容。如果你有二级目录，也应该放置一份配置文件。 -**如果用 `_` 开头作为文件名，你应该在文档目录下添加 `.nojekyll`，阻止 GitHub Pages 忽略下划线开头的文件。** - -```html - -``` - - -你可以指定侧边栏文件名 - -```html - -``` - -```js -window.$docsify = { - loadSidebar: '_sidebar.md' -} -``` - -`_sidebar.md` 的内容可以是这样的 - -```markdown -- [Home](/) -- [Installation](/installation) -- Essentials - - [Getting Started](/getting-started) - - [Dynamic Route Matching](/dynamic-matching) - - [Nested Routes](/nested-routes) -``` - -### sub-max-level - -显示 TOC 在自定义的侧边栏里，默认最大显示 0 层。 - - -```html - -``` - -```js -window.$docsify = { - maxSubLevel: 4 -} -``` - -### load-navbar - -读取导航配置文件，如果配置，默认加载当前目录下的 `_navbar.md`。如果文件不存在，会显示 html 里定义的导航栏。 - -```html - -``` - -你可以指定导航栏文件名 - -```html - -``` - -```js -window.$docsify = { - loadNavbar: '_navbar.md' -} -``` - -`_navbar.md` 的内容可以是这样 - -```markdown -- [en](/) -- [中文](/zh-cn) -``` - -当然也支持二级列表，将生成一个下拉列表 -```markdown -- [download](/download) -- language - - [en](/) - - [中文](/zh-cn) -``` - - -### auto2top - -切换路由时自动跳转到页面顶部 - - -```html - -``` - -```js -window.$docsify = { - auto2top: true -} -``` - -### homepage - -默认情况下网站会将根目录下 `README.md` 作为首页渲染，但是有些时候我们想指定其他文件，甚至想直接将 repo 下的 README 作为首页。 - - -```html - - - -``` - -```js -window.$docsify = { - homepage: true -} -``` - -### base-path - -指定加载文档的路径，如果你的 HTML 入口文件和文档是放在不同地方，你可以设置： - -```html - - - - -``` - - -```js -window.$docsify = { - basePath: '/base/' -} -``` - -### coverpage - -生成封面，参考 [#封面](/zh-cn#封面). - -```html - - - - -``` - - -```js -window.$docsify = { - coverpage: true -} -``` - - -### name - -项目名，将显示在侧边栏。 - -```html - -``` - -```js -window.$docsify = { - name: 'docsify' -} -``` - -### name-link - -项目名链接，默认为 `window.location.pathname`。 - -```html - -``` - -```js -window.$docsify = { - nameLink: '/' -} -``` - -### theme-color - -自定义主题色。 - - -```html - -``` - -```js -window.$docsify = { - themeColor: '#3F51B5' -} -``` - -### alias - -设置别名方便自定义路由或者引入其他文件。 - -```js -window.$docsify = { - alias: { - '/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG' - } -} -``` - -## Plugins - -### 全文检索 - search - -一份文档如果能有搜索功能会提升一些用户体验，加载搜索插件也很简单，直接引入就自动安装并启用。默认情况下会自动分析当前页面上的超链接，获取内容后建立索引并存储在 `localStorage` 里，默认过期时间为一天，当然这是可配置的。 - -自动识别的方式不一定能识别完整或者如果你想指定某些文件可索引，你可以自己指定文件的路径。 - -```html - - -``` - -!> 配置要在 docsify 引入之前 - -```js -window.$docsify = { - search: 'auto', // default - - search : [ - '/', // => /README.md - '/guide', // => /guide.md - '/get-started', // => /get-started.md - '/zh-cn/', // => /zh-cn/README.md - ], - - // Full configuration - search: { - maxAge: 86400000, // Expiration time, the default one day - paths: [], // or 'auto' - placeholder: 'Type to search' - } -} -``` - -### Google Analytics - -安装插件并且配置 track id。 - -```html - - -``` - -或者 - -```js -window.$docsify = { - ga: 'UA-XXXXX-Y' -} -``` diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md index 4aa91ca1..27d26475 100644 --- a/docs/zh-cn/README.md +++ b/docs/zh-cn/README.md @@ -24,4 +24,4 @@ docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo ## 捐赠 -如果你觉得 docsify 对你有帮助，或者想对我的工作一点资瓷，欢迎给我[捐赠](https://github.com/QingWei-Li/donate)。 \ No newline at end of file +如果你觉得 docsify 对你有帮助，或者想对我微小的工作一些资瓷，欢迎给我[捐赠](https://github.com/QingWei-Li/donate)。 \ No newline at end of file diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md index 7253e908..e911c388 100644 --- a/docs/zh-cn/_sidebar.md +++ b/docs/zh-cn/_sidebar.md @@ -1,4 +1,4 @@ -- 基础 +- 入门 - [快速开始](zh-cn/quickstart) - [多页文档](zh-cn/more-pages) - [定制导航栏](zh-cn/custom-navbar)