配置 v-no

The documentation is a work in progress, and English edition is just an empty shell for now. I will translate it when Chinese edition has done.

v-no 的配置相当灵活，除了少数几个只能在编译前修改的环境变量，其它配置项都储存在 assets/config.js 文件的 vnoConfig 对象中。它随页面载入，并且暴露在全局供所有脚本访问。这意味着你只需刷新页面就可以让配置的更新生效（如果你比较在意浏览器缓存，可以先看看这里）。

这是默认的 assets/config.js 文件：

vnoConfig = {
  siteName: '',
  dateFormat: '',
  smartQuotes: '',
  replacer: [],
  cdn: '',
  cacheKey: '',
  paths: {
    favicon: '/uploads/favicon.png',
    index: '/index.md',
    readme: '/README.md',
    archive: '/archives.md',
    category: '/categories.md',
    search: '/search.md',
    common: '/common.md',
  },
  messages: {
    home: 'HOME',
    raw: 'Raw',
    footnotes: 'Footnotes:',
    returnHome: 'Return to home',
    lastUpdated: 'Last updated',
    untagged: 'untagged',
    pageError: 'There is something wrong with this page.',
    searching: 'Searching...',
    searchNothing: 'Nothing.',
    showBacklinks: 'Show backlinks',
    noBacklinks: 'No backlinks.',
    loading: 'Loading...',
    redirectFrom: 'Redirect from: ',
  },
  defaultConf: '',
  multiConf: {},};

它由主配置和多配置两部分组成，可以为空的配置项也可以省略不写。

主配置
- paths 段
- messages 段
多配置
- 自动切换配置

主配置


`siteName`	站点名称。它会作为顶栏左侧图标旁指向主页的链接文本，也会被加到页面 `<title>` 后。如果此项为空，`messages.home` 会顶替上来，不过它不会被加进 `<title>`。
`dateFormat`	日期格式化字符串。v-no 使用 Day.js 格式化日期，你可以参考支持的格式化占位符列表填写。如果此项为空，会使用 `Date` 对象的 `toDateString()` 方法进行格式化（`ddd MMM DD YYYY`）。
`smartQuotes`	用于将非开闭引号（`"'`）转换为开闭引号的字符串或字符串数组。它会直接传入 markdown-it 的 `quotes` 字段用于初始化。你需要为它提供四个字符或字符串，分别指示双开闭引号和单开闭引号（比如 `“”‘’`）。如果此项为空，或者长度小于四，都不会启用引号转换。
`replacer`	用于在渲染过程中对一般文本进行替换的二维字符串数组。v-no 会遍历外层数组，用内部数组的第一个值构建全局正则表达式，并用第二个值替换它匹配到的字符串。因为结果是递进的，你可能需要注意一下它们的排列顺序。如果此项为空，它会被忽略。
`cdn`	网站使用的 CDN 地址，需要以 `/` 结尾。它会被加到除 v-no 自身代码文件和配置文件以外的所有以 `/` 开头的站内链接的前面。你可以在这里找到更多有关 CDN 的内容。如果此项为空，它会被忽略。
`cacheKey`	用于主动控制浏览器缓存的字符串或对象。如果这是一个字符串，它会被加到所有 `.md` 文件请求和自定义脚本 / 自定义样式链接的后面；如果它是一个对象，会被加到链接后的就是以文件路径为键对它索引到的值。如果你启用了 CDN，它并不能保证 CDN 会刷新它的缓存。你可以在这里找到更多有关浏览器缓存的内容。如果此项为空，它会被忽略。

paths 段

这里列出的配置项需要填入以 assets/ 所在目录为根目录的绝对路径。

请保证它们以 / 开头、favicon 以外的文件路径以 .md 结尾，以及路径指向的文件都是存在的。只有 favicon 和 common 可以为空。


`favicon`	favicon 路径。除了浏览器标签页，它也会展示在顶栏的最左边。选用图片的分辨率最好大于 `24 x 24` 像素。如果此项为空，它会被忽略。
`index`	主页文件路径。它是在 URL 无 Hash 部分时默认展示的文件，请把它当作网站的起点。需要注意，如果此项为 `/index.md`，`localhost/` 和 `localhost/#/` 都会指向它，但后者只是因为 `index.md` 被省略了。
`readme`	读我文件路径。因为 `README.md` 是 GitHub 之类的托管网站默认展示的文件，一般把它作为仓库的起点。你当然也可以仅仅把它当作顶栏右侧第一个链接指向的文件。
`archive`	归档文件路径。一般把它用作文件索引、集中存放对其它文件的引用。它是顶栏右侧第二个链接指向的文件，和 `readme` 一样，一般怎么用只是个约定，除了固定在顶栏，它们和普通文件没有更多区别。
`category`	分类文件路径。它被用于渲染分类页，承载了按标签自动汇总所有能被检索到的 `.md` 文件的功能。它是顶栏右侧第三个链接指向的文件，除了默认包含一个无参数生成列表，也只是个普通文件。
`search`	搜索文件路径。它被用于渲染搜索页，承载了在所有能被检索到的 `.md` 文件中进行搜索的功能。它是顶栏右侧第四个链接指向的文件，会被预处理。
`common`	通用文件路径。它会被加进除自己以外的其它文件中一并渲染，默认会加到文件尾。如果你使用 `--8<--` 将它分成两部分，它们就会分别加到文件头和文件尾。如果此项为空，它会被忽略。

messages 段

方便进行本地化（l10n）的一些配置项。


`home`	`siteName` 为空时的替代，不会被加进 `<title>`。
`raw`	页头指向原始文件的链接文本。
`footnotes`	文章底部加在脚注列表上方的文本。
`returnHome`	页脚指向主页的链接文本。
`lastUpdated`	在页面有多个不同的日期时，页脚右侧日期旁的文本。
`untagged`	分类页里没有标签的页面的分类名。
`pageError`	页面出错时用于构建错误文件的文本。它和普通文件享有同样的待遇，这意味着你可以使用嵌入链接导入一个专门的错误页放在这里。
`searching`	搜索页正在搜索时的文本。
`searchNothing`	搜索页的搜索结果为空时的文本。
`showBacklinks`	页脚上方查看反链的链接文本。
`noBacklinks`	没有反链时的文本。
`loading`	正在加载反链时的文本。
`redirectFrom`	重定向链接前的文本。

最后两个配置项属于多配置部分。

多配置

多配置是可以自由切换的、会覆盖到主配置的多组备用配置项。

因为只要更换 paths 段指定的 .md 文件就可以索引到不同的内容，你可以用它在同一个地方构建多个独立索引的内容分区。没错，它可以用来做国际化（i18n）。


`defaultConf`	`localStorage` 没有相关记录时，默认选择的配置名。如果此项为空，会停用多配置。
`multiConf`	键为配置名、值为主配置子集的对象。只有此项列出的配置组的个数多于一个时，才会启用多配置。
`alias`	它不在默认配置中，只用在 `multiConf` 为当前配置组指定一个别名。

多配置在启用后，顶栏的最右边会出现一个选择框供切换配置使用。它会将选定的配置名记录到 localStorage 以便之后读取。

v-no 会尝试从 multiConf 中取出指定配置名下的一组配置项，并将它覆盖到外层主配置上。如果没有与 localStorage 记录的配置名对应的配置组，记录会被清除，并尝试用默认配置组继续。

这里是一个多配置写法的示例：

vnoConfig = {
  // 这里为了避免重复，把主配置略去了。
  // 因为下面任意一组配置项都构不成可用的主配置，这里实际是不能省的。
  defaultConf: 'en',
  multiConf: {
    en: {
      alias: 'English',
    },
    zh: {
      alias: '中文 (简体)',
      dateFormat: 'YYYY 年 MM 月 DD 日',
      messages: {
        home: '主页',
      },
    },
    jp: {
      alias: '日本語',
      messages: {
        home: 'ホームページ',
      },
    },
  },};

如果 multiConf 只有一组配置项，虽然不会启用多配置，但你只要在 defaultConf 指定了它，对主配置的覆盖也会进行。所以，你也可以把外层主配置全部移动到 multiConf 中，这样配置文件会更加整洁。只要主配置最后是完整可用的，v-no 就可以正常运作。

自动切换配置

多配置所构建的内容分区之间并不是互相隔离的。v-no 也无法将 .md 文件和某组配置项关联起来，尤其是直接从 URL 访问，而不是经路由跳转的页面。所以，只在配置 A 中被索引的文件也能在启用配置 B 的时候被渲染。

你可能不希望这样的事发生，不过 v-no 确实没有能力从根本上解决这个问题（除非阻止渲染……不过那也太霸道了）。为了稍微缓解它，这里增加了一个自动切换配置的机制。

你可以在 URL 的最后加入类似 ?conf=name 的查询字符串来指定目标配置名，页面会在重载时尝试切换到这组配置项。另外，路由跳转是不会重载页面的，它在这种情况下也不会生效，你需要刷新一下才行。

: This page is open source, improve it

Graph