From 4bdcee2cb31a6a21bb40d0774e5081ae02cd5534 Mon Sep 17 00:00:00 2001 From: "qingwei.li" Date: Sun, 11 Feb 2018 20:12:07 +0800 Subject: [PATCH] docs: add mutiple covers --- docs/configuration.md | 25 ++++++++++++++-- docs/cover.md | 49 ++++++++++++++++++++++++++++-- docs/custom-navbar.md | 37 ++++++++++++----------- docs/de-de/configuration.md | 11 ++++++- docs/de-de/cover.md | 49 ++++++++++++++++++++++++++++-- docs/de-de/custom-navbar.md | 37 ++++++++++++----------- docs/de-de/more-pages.md | 12 ++++---- docs/more-pages.md | 12 ++++---- docs/zh-cn/configuration.md | 11 ++++++- docs/zh-cn/cover.md | 59 +++++++++++++++++++++++++++++++------ docs/zh-cn/custom-navbar.md | 41 ++++++++++++-------------- docs/zh-cn/more-pages.md | 12 ++++---- 12 files changed, 262 insertions(+), 93 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 137429e3..4d26d0d6 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -152,7 +152,7 @@ window.$docsify = { ## coverpage -* Type: `Boolean|String` +* Type: `Boolean|String|String[]|Object` * Default: `false` Activate the [cover feature](cover.md). If true, it will load from `_coverpage.md`. @@ -162,7 +162,16 @@ window.$docsify = { coverpage: true, // Custom file name - coverpage: 'cover.md' + coverpage: 'cover.md', + + // mutiple covers + coverpage: ['/', '/zh-cn/'], + + // mutiple covers and custom file name + coverpage: { + '/': 'cover.md', + '/zh-cn/': 'cover.md' + } }; ``` @@ -367,4 +376,16 @@ window.$docsify = { }; ``` +## onlyCover + +* type: `Boolean` + +Only coverpage is loaded when When visiting the home page. + +```js +window.$docsify = { + onlyCover: false +}; +``` + ## diff --git a/docs/cover.md b/docs/cover.md index f91b71e6..31b87599 100644 --- a/docs/cover.md +++ b/docs/cover.md @@ -26,9 +26,9 @@ Set `coverpage` to **true**, and create a `_coverpage.md`: > A magical documentation site generator. -- Simple and lightweight (~18kB gzipped) -- No statically built html files -- Multiple themes +* Simple and lightweight (~18kB gzipped) +* No statically built html files +* Multiple themes [GitHub](https://github.com/QingWei-Li/docsify/) [Get Started](#docsify) @@ -49,8 +49,51 @@ The background color is generated randomly by default. You can customize the bac [Get Started](#quick-start) + ![](_media/bg.png) + ![color](#f0f0f0) ``` + +## Coverpage as homepage + +Normal, the coverpage and the homepage appear at the same time. Of course, you can also separate the coverpage by [onlyCover option](configuration.md#onlycover). + +## Multiple covers + +If your docs site is in more than one language, it may be useful to set multiple covers. + +For example, your docs structure is like this + +```text +. +└── docs + ├── README.md + ├── guide.md + ├── _coverpage.md + └── zh-cn + ├── README.md + └── guide.md + └── _coverpage.md +``` + +Now, you can set + +```js +window.$docsify = { + coverpage: ['/', '/zh-cn/'] +}; +``` + +Or a special file name + +```js +window.$docsify = { + coverpage: { + '/': 'cover.md', + '/zh-cn/': 'cover.md' + } +}; +``` diff --git a/docs/custom-navbar.md b/docs/custom-navbar.md index 1642918c..324ad810 100644 --- a/docs/custom-navbar.md +++ b/docs/custom-navbar.md @@ -20,7 +20,7 @@ If you need custom navigation, you can create a HTML-based navigation bar. ## Markdown -Alternatively, you can create a custom markdown-based navigation file by setting `loadNavbar` to **true** and creating `_navbar.md`, compare [load-navbar configuration](configuration.md#load-navbar). +Alternatively, you can create a custom markdown-based navigation file by setting `loadNavbar` to **true** and creating `_navbar.md`, compare [loadNavbar configuration](configuration.md#loadnavbar). ```html @@ -36,13 +36,13 @@ Alternatively, you can create a custom markdown-based navigation file by setting ```markdown -- [En](/) -- [chinese](/zh-cn/) +* [En](/) +* [chinese](/zh-cn/) ``` !> You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore. -`_navbar.md` is loaded from each level directory. If the current directory doesn't have `_navbar.md`, it will fall back to the parent directory. If, for example, the current path is `/guide/quick-start`, the `_navbar.md` will be loaded from `/guide/_navbar.md`. +`_navbar.md` is loaded from each level directory. If the current directory doesn't have `_navbar.md`, it will fall back to the parent directory. If, for example, the current path is `/guide/quick-start`, the `_navbar.md` will be loaded from `/guide/_navbar.md`. ## Nesting @@ -51,23 +51,24 @@ You can create sub-lists by indenting items that are under a certain parent. ```markdown -- Getting started - - [Quick start](quickstart.md) - - [Writing more pages](more-pages.md) - - [Custom navbar](custom-navbar.md) - - [Cover page](cover.md) +* Getting started -- Configuration - - [Configuration](configuration.md) - - [Themes](themes.md) - - [Using plugins](plugins.md) - - [Markdown configuration](markdown.md) - - [Language highlight](language-highlight.md) + * [Quick start](quickstart.md) + * [Writing more pages](more-pages.md) + * [Custom navbar](custom-navbar.md) + * [Cover page](cover.md) + +* Configuration + * [Configuration](configuration.md) + * [Themes](themes.md) + * [Using plugins](plugins.md) + * [Markdown configuration](markdown.md) + * [Language highlight](language-highlight.md) ``` renders as -![Nesting navbar](_images/nested-navbar.png "Nesting navbar") +![Nesting navbar](_images/nested-navbar.png 'Nesting navbar') ## Combining custom navbars with the emoji plugin @@ -90,6 +91,6 @@ you could, for example, use flag emojis in your custom navbar Markdown file: ```markdown -- [:us:, :uk:](/) -- [:cn:](/zh-cn/) +* [:us:, :uk:](/) +* [:cn:](/zh-cn/) ``` diff --git a/docs/de-de/configuration.md b/docs/de-de/configuration.md index 3f46d550..33e39674 100644 --- a/docs/de-de/configuration.md +++ b/docs/de-de/configuration.md @@ -162,7 +162,16 @@ window.$docsify = { coverpage: true, // Anderer Dateiname - coverpage: 'cover.md' + coverpage: 'cover.md', + + // mutiple covers + coverpage: ['/', '/zh-cn/'], + + // mutiple covers and custom file name + coverpage: { + '/': 'cover.md', + '/zh-cn/': 'cover.md' + } }; ``` diff --git a/docs/de-de/cover.md b/docs/de-de/cover.md index e4513cdb..1f3c8e51 100644 --- a/docs/de-de/cover.md +++ b/docs/de-de/cover.md @@ -26,9 +26,9 @@ Setze `coverpage` auf **true**, und erstelle `_coverpage.md`: > Ein magischer Generator für Dokumentationsseiten. -- Einfach und wenig Speicherbedarf (~18kB gzipped) -- Keine statischen HTML Dateien -- Mehrere Themes +* Einfach und wenig Speicherbedarf (~18kB gzipped) +* Keine statischen HTML Dateien +* Mehrere Themes [GitHub](https://github.com/QingWei-Li/docsify/) [Schnellstart](#docsify) @@ -49,8 +49,51 @@ Die Hintergrundfarbe wird in der Standardeinstellung zufällig generiert. Du kan [Schnellstart](#quick-start) + ![](_media/bg.png) + ![color](#f0f0f0) ``` + +## Coverpage as homepage + +Normal, the coverpage and the homepage appear at the same time. Of course, you can also separate the coverpage by [onlyCover option](de-de/configuration.md#onlycover). + +## Multiple covers + +If your docs site is in more than one language, it may be useful to set multiple covers. + +For example, your docs structure is like this + +```text +. +└── docs + ├── README.md + ├── guide.md + ├── _coverpage.md + └── zh-cn + ├── README.md + └── guide.md + └── _coverpage.md +``` + +Now, you can set + +```js +window.$docsify = { + coverpage: ['/', '/zh-cn/'] +}; +``` + +Or a special file name + +```js +window.$docsify = { + coverpage: { + '/': 'cover.md', + '/zh-cn/': 'cover.md' + } +}; +``` diff --git a/docs/de-de/custom-navbar.md b/docs/de-de/custom-navbar.md index 7ec8681f..819d05ad 100644 --- a/docs/de-de/custom-navbar.md +++ b/docs/de-de/custom-navbar.md @@ -20,7 +20,7 @@ Solltest du eine Navigationsleiste benötigen, so kannst du eine HTML-basierte e ## Markdown -Oder du kannst deine Navigationsleiste mit einer Datei basierend auf Markdown erstellen, indem du `loadNavbar` auf **true** setzt und eine Datei namens `_navbar.md` erstellst, vergleiche [load-navbar Einstellungen](configuration.md#load-navbar). +Oder du kannst deine Navigationsleiste mit einer Datei basierend auf Markdown erstellen, indem du `loadNavbar` auf **true** setzt und eine Datei namens `_navbar.md` erstellst, vergleiche [loadNavbar Einstellungen](configuration.md#loadnavbar). ```html @@ -36,13 +36,13 @@ Oder du kannst deine Navigationsleiste mit einer Datei basierend auf Markdown er ```markdown -- [En](/) -- [Deutsch](/de-de/) +* [En](/) +* [Deutsch](/de-de/) ``` !> Solltest du Github Pages verwenden, musst du zusätzlich eine Datei namens `.nojekyll` in `./docs` erstellen, um zu verhindern, dass Github Dateien ignoriert, die mit einem Unterstrich anfangen. -`_navbar.md` wird in jedem Verzeichnislevel geladen. Sollte das aktuelle Verzeichnis keine Datei namens `_navbar.md` haben, so sucht **docsify** in den übergeordneten Ordnern. Wenn du z.B. im Moment im Verzeichnis `/guide/quick-start` bist, so wird `_navbar.md` von der Datei `/guide/_navbar.md` geladen. +`_navbar.md` wird in jedem Verzeichnislevel geladen. Sollte das aktuelle Verzeichnis keine Datei namens `_navbar.md` haben, so sucht **docsify** in den übergeordneten Ordnern. Wenn du z.B. im Moment im Verzeichnis `/guide/quick-start` bist, so wird `_navbar.md` von der Datei `/guide/_navbar.md` geladen. ## Aufbauen von Strukturen @@ -51,23 +51,24 @@ Du kannst untergeordnete Listen erstellen, indem du untergeordnete Punkte einem ```markdown -- Getting started - - [Quick start](de-de/quickstart.md) - - [Writing more pages](de-de/more-pages.md) - - [Custom navbar](de-de/custom-navbar.md) - - [Cover page](de-de/cover.md) +* Getting started -- Configuration - - [Configuration](de-de/configuration.md) - - [Themes](de-de/themes.md) - - [Using plugins](de-de/plugins.md) - - [Markdown configuration](de-de/markdown.md) - - [Language highlight](de-de/language-highlight.md) + * [Quick start](de-de/quickstart.md) + * [Writing more pages](de-de/more-pages.md) + * [Custom navbar](de-de/custom-navbar.md) + * [Cover page](de-de/cover.md) + +* Configuration + * [Configuration](de-de/configuration.md) + * [Themes](de-de/themes.md) + * [Using plugins](de-de/plugins.md) + * [Markdown configuration](de-de/markdown.md) + * [Language highlight](de-de/language-highlight.md) ``` wird also wie folgt aussehen -![Nesting navbar](_images/nested-navbar.png "Nesting navbar") +![Nesting navbar](_images/nested-navbar.png 'Nesting navbar') ## Angepasste Navigationsleisten in Verbindung mit dem emoji Erweiterung @@ -90,6 +91,6 @@ so kannst du z.B. auch die Flaggenemojis in der Markdown Datei für deine angepa ```markdown -- [:us:, :uk:](/) -- [:de:](/de-de/) +* [:us:, :uk:](/) +* [:de:](/de-de/) ``` diff --git a/docs/de-de/more-pages.md b/docs/de-de/more-pages.md index a82d2b5e..1cfc0019 100644 --- a/docs/de-de/more-pages.md +++ b/docs/de-de/more-pages.md @@ -27,7 +27,7 @@ docs/de-de/guide.md => http://domain.com/de-de/guide Als Standardeinstellung wird das Inhaltsverzeichnis in der Seitenleiste automatisch basierend auf vorhandenen Markdown Dateien generiert. Wenn du das seitliche Inhaltsverzeichnis anpassen willst, kannst du eine Datei namens `_sidebar.md` erstellen (vergleiche [das seitliche Inhaltsverzeichnis für diese Dokumentation](https://github.com/QingWei-Li/docsify/blob/master/docs/de-de/_sidebar.md) als Beispiel): -Als Erstes musst du `loadSidebar` auf **true** setzen, vergleiche [Einstellungen für das seitliche Inhaltsverzeichnis](configuration.md#load-sidebar). +Als Erstes musst du `loadSidebar` auf **true** setzen, vergleiche [Einstellungen für das seitliche Inhaltsverzeichnis](configuration.md#loadsidebar). ```html @@ -45,13 +45,13 @@ Als Zweites erstellst du eine Datei namens `_sidebar.md`: ```markdown -- [Home](/) -- [Guide](de-de/guide.md) +* [Home](/) +* [Guide](de-de/guide.md) ``` !> Solltest du Github Pages verwenden, musst du zusätzlich eine Datei namens `.nojekyll` in `./docs` erstellen, um zu verhindern, dass Github Dateien ignoriert, die mit einem Unterstrich anfangen. -`_sidebar.md` wird in jedem Verzeichnislevel geladen. Sollte das aktuelle Verzeichnis keine Datei namens `_sidebar.md` haben, so sucht **docsify** in den übergeordneten Ordnern. Wenn du z.B. im Moment im Verzeichnis `/guide/quick-start` bist, so wird `_sidebar.md` von der Datei `/guide/_sidebar.md` geladen. +`_sidebar.md` wird in jedem Verzeichnislevel geladen. Sollte das aktuelle Verzeichnis keine Datei namens `_sidebar.md` haben, so sucht **docsify** in den übergeordneten Ordnern. Wenn du z.B. im Moment im Verzeichnis `/guide/quick-start` bist, so wird `_sidebar.md` von der Datei `/guide/_sidebar.md` geladen. You can specify `alias` to avoid unnecessary fallback. @@ -68,7 +68,7 @@ You can specify `alias` to avoid unnecessary fallback. ## Inhaltsverzeichnis -Eine angepasste Seitenleist kann auch automatisch ein Inhaltsverzeichnis generieren, indem ein `subMaxLevel` gesetzt wird, vergleiche [sub-max-level Einstellungen](configuration.md#sub-max-level). +Eine angepasste Seitenleist kann auch automatisch ein Inhaltsverzeichnis generieren, indem ein `subMaxLevel` gesetzt wird, vergleiche [subMaxLevel Einstellungen](configuration.md#submaxlevel). ```html @@ -90,6 +90,7 @@ When `subMaxLevel` is set, each header is automatically added to the table of co # Getting Started ## Header {docsify-ignore} + This header won't appear in the sidebar table of contents. ``` @@ -99,6 +100,7 @@ To ignore all headers on a specific page, you can use `{docsify-ignore-all}` on # Getting Started {docsify-ignore-all} ## Header + This header won't appear in the sidebar table of contents. ``` diff --git a/docs/more-pages.md b/docs/more-pages.md index ff77bb90..0b4d77dd 100644 --- a/docs/more-pages.md +++ b/docs/more-pages.md @@ -27,7 +27,7 @@ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide In order to have sidebar, then you can create your own `_sidebar.md` (see [this documentation's sidebar](https://github.com/QingWei-Li/docsify/blob/master/docs/_sidebar.md) for an example): -First, you need to set `loadSidebar` to **true**. Details are available in the [configuration paragraph](configuration.md#load-sidebar). +First, you need to set `loadSidebar` to **true**. Details are available in the [configuration paragraph](configuration.md#loadsidebar). ```html @@ -45,13 +45,13 @@ Create the `_sidebar.md`: ```markdown -- [Home](/) -- [Guide](guide.md) +* [Home](/) +* [Guide](guide.md) ``` You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore. -`_sidebar.md` is loaded from each level directory. If the current directory doesn't have `_sidebar.md`, it will fall back to the parent directory. If, for example, the current path is `/guide/quick-start`, the `_sidebar.md` will be loaded from `/guide/_sidebar.md`. +`_sidebar.md` is loaded from each level directory. If the current directory doesn't have `_sidebar.md`, it will fall back to the parent directory. If, for example, the current path is `/guide/quick-start`, the `_sidebar.md` will be loaded from `/guide/_sidebar.md`. You can specify `alias` to avoid unnecessary fallback. @@ -70,7 +70,7 @@ You can specify `alias` to avoid unnecessary fallback. Once you've created `_sidebar.md`, the sidebar content is automatically generated based on the headers in the markdown files. -A custom sidebar can also automatically generate a table of contents by setting a `subMaxLevel`, compare [sub-max-level configuration](configuration.md#sub-max-level). +A custom sidebar can also automatically generate a table of contents by setting a `subMaxLevel`, compare [subMaxLevel configuration](configuration.md#submaxlevel). ```html @@ -92,6 +92,7 @@ When `subMaxLevel` is set, each header is automatically added to the table of co # Getting Started ## Header {docsify-ignore} + This header won't appear in the sidebar table of contents. ``` @@ -101,6 +102,7 @@ To ignore all headers on a specific page, you can use `{docsify-ignore-all}` on # Getting Started {docsify-ignore-all} ## Header + This header won't appear in the sidebar table of contents. ``` diff --git a/docs/zh-cn/configuration.md b/docs/zh-cn/configuration.md index 0c3d8066..6c807f57 100644 --- a/docs/zh-cn/configuration.md +++ b/docs/zh-cn/configuration.md @@ -175,7 +175,16 @@ window.$docsify = { coverpage: true, // 自定义文件名 - coverpage: 'cover.md' + coverpage: 'cover.md', + + // mutiple covers + coverpage: ['/', '/zh-cn/'], + + // mutiple covers and custom file name + coverpage: { + '/': 'cover.md', + '/zh-cn/': 'cover.md' + } }; ``` diff --git a/docs/zh-cn/cover.md b/docs/zh-cn/cover.md index 92f9425c..25026d28 100644 --- a/docs/zh-cn/cover.md +++ b/docs/zh-cn/cover.md @@ -6,7 +6,7 @@ 封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 `_coverpage.md` 文件。渲染效果如本文档。 -*index.html* +_index.html_ ```html ``` -*_coverpage.md* +_\_coverpage.md_ ```markdown ![logo](_media/icon.svg) @@ -26,24 +26,21 @@ > A magical documentation site generator. -- Simple and lightweight (~12kb gzipped) -- Multiple themes -- Not build static html files - +* Simple and lightweight (~12kb gzipped) +* Multiple themes +* Not build static html files [GitHub](https://github.com/QingWei-Li/docsify/) [Get Started](#quick-start) ``` - - !> 一份文档只会在根目录下加载封面，其他页面或者二级目录下都不会加载。 ## 自定义背景 目前的背景是随机生成的渐变色，我们自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。 -*_coverpage.md* +_\_coverpage.md_ ```markdown # docsify @@ -52,7 +49,51 @@ [Get Started](#quick-start) + ![](_media/bg.png) + + ![color](#f0f0f0) ``` + +## 封面作为首页 + +通常封面和首页是同时出现的，当然你也是当封面独立出来通过设置[onlyCover 选项](zh-cn/configuration.md#onlycover)。 + +## 多个封面 + +如果你的文档网站是多语言的，或许你需要设置多个封面。 + +例如你的文档目录结构如下 + +```text +. +└── docs + ├── README.md + ├── guide.md + ├── _coverpage.md + └── zh-cn + ├── README.md + └── guide.md + └── _coverpage.md +``` + +那么你可以这么配置 + +```js +window.$docsify = { + coverpage: ['/', '/zh-cn/'] +}; +``` + +或者具体指名文件名 + +```js +window.$docsify = { + coverpage: { + '/': 'cover.md', + '/zh-cn/': 'cover.md' + } +}; +``` diff --git a/docs/zh-cn/custom-navbar.md b/docs/zh-cn/custom-navbar.md index ccb97d30..c6ca8032 100644 --- a/docs/zh-cn/custom-navbar.md +++ b/docs/zh-cn/custom-navbar.md @@ -2,7 +2,7 @@ 我们可以直接在 HTML 里定义导航栏，要注意链接要以 `#/` 开头。 -*index.html* +_index.html_ ```html @@ -14,13 +14,11 @@ ``` - ## 配置文件 -那我们可以通过 Markdown 文件来配置导航。首先配置 `loadNavbar`，默认加载的文件为 `_navbar.md`。具体配置规则见[配置项#load-navbar](configuration.md#load-navbar)。 - -*index.html* +那我们可以通过 Markdown 文件来配置导航。首先配置 `loadNavbar`，默认加载的文件为 `_navbar.md`。具体配置规则见[配置项#loadNavbar](configuration.md#loadnavbar)。 +_index.html_ ```html ``` -*_navbar.md* +_\_navbar.md_ ```markdown -- [En](/) -- [中文](/zh-cn/) +* [En](/) +* [中文](/zh-cn/) ``` `_navbar.md` 加载逻辑和 `sidebar` 文件一致，从每层目录下获取。例如当前路由为 `/zh-cn/custom-navbar` 那么是从 `/zh-cn/_navbar.md` 获取导航栏。 @@ -44,24 +42,23 @@ 如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式。 -*_navbar.md* - +_\_navbar.md_ ```markdown -- 基础 - - [快速开始](zh-cn/quickstart.md) - - [多页文档](zh-cn/more-pages.md) - - [定制导航栏](zh-cn/custom-navbar.md) - - [封面](zh-cn/cover.md) +* 基础 +* [快速开始](zh-cn/quickstart.md) +* [多页文档](zh-cn/more-pages.md) +* [定制导航栏](zh-cn/custom-navbar.md) +* [封面](zh-cn/cover.md) -- 配置 - - [配置项](zh-cn/configuration.md) - - [主题](zh-cn/themes.md) - - [使用插件](zh-cn/plugins.md) - - [Markdown 配置](zh-cn/markdown.md) - - [代码高亮](zh-cn/language-highlight.md) +* 配置 + * [配置项](zh-cn/configuration.md) + * [主题](zh-cn/themes.md) + * [使用插件](zh-cn/plugins.md) + * [Markdown 配置](zh-cn/markdown.md) + * [代码高亮](zh-cn/language-highlight.md) ``` 效果图 -![嵌套导航栏](_images/zh-cn/nested-navbar.png "嵌套导航栏") +![嵌套导航栏](_images/zh-cn/nested-navbar.png '嵌套导航栏') diff --git a/docs/zh-cn/more-pages.md b/docs/zh-cn/more-pages.md index b359474f..910273b7 100644 --- a/docs/zh-cn/more-pages.md +++ b/docs/zh-cn/more-pages.md @@ -26,7 +26,7 @@ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide 默认情况下，侧边栏会根据当前文档的标题生成目录。也可以设置文档链接，通过 Markdown 文件生成，效果如当前的文档的侧边栏。 -首先配置 `loadSidebar` 选项，具体配置规则见[配置项#load-sidebar](configuration.md#load-sidebar)。 +首先配置 `loadSidebar` 选项，具体配置规则见[配置项#loadSidebar](configuration.md#loadsidebar)。 ```html