这种错误表现在空表格上。例如，我在Markdown中如下编写表格：

|   |   |   |
|---|---|---|
|   |   |   |

应该显示为这样：

但在网页中却显示为这样：

只有在将表格填满后才能不再显示|。

复现步骤

• MacOS 操作系统；
• teadocs dev 启动项目；
• 点击终端中的链接，无法在浏览器中打开页面；

window 操作系统不知道可有这问题，没有机器，没测~

原因

当鼠标放到链接上时，可以看到链接下划线包含了右中括弧 ]。

解决

中括弧前后加空格，可以看到链接下划线只包含链接本身，测试点击可以打开网址了 ~~~

需求

根据文章内的一级标题、二级标题、三级标题，生成文章目录，

• 一来看文章目录就可以知道大致要说哪些内容了；
• 二来文档本身是具有查询属性，点击对应目录标题，可以快速定位到标题所在位置。

方案

web 端页面右侧刚好有一片空白区域，可以用来放文章目录；

做成响应式，浏览器宽度小于一定值，不显示文章目录；

markdown 文档内没有用到一级标题、二级标题、三级标题的，不生成文章目录；

手机端由于屏幕太小，不显示文章目录。

@lisniuse 大佬看还有啥要补充的不~~~

示例网站

• Ant-design 官方文档
• Segmentfault

需求背景

teadocs 可能用于团队博客，希望每篇文档能够显示编写的作者；

技术文档一般都有时序性，比如之前写过文章吐槽过 React 的函数式组件没有内部状态，在 React 16+ 版本之后支持了 Hook 特性，那么之前那篇文章就没有参考价值了。希望文档中显示文章的创建时间和修改时间，以供读者参考。

思路

参考 Hexo，如果用户需要显示作者以及创建时间，在 markdown 头部添加 yaml 语法

如果头部没有 yaml 语法，不会有任何影响，完美兼容已有用户

For Example（front matter格式）

---
author: dkvirus
date: 2018-08-14 08:55:10
updated: 2018-08-14 16:26:48
---

文档的内容
文档的内容
文档的内容

属性名字段规范，这样 Hexo 的文章可以直接迁移过来

• 作者 author，字符串或者数组，如果是数组，用逗号分隔作者名
• 创建时间 date
• 更新时间 updated

ui 显示

调研了一些在线文档工具的显示。

• 语雀：作者以及时间显示在文章底部；
• 简书：作者以及时间显示在文章标题下面；
• 开源**：作者以及时间显示在文章标题下面；
• infoQ：作者以及时间显示在文章标题下面；

最后

我先尝试把功能加上， @lisniuse 后面看样式不行的话，麻烦完善一下哈。

正确是teadocs init mydocs

问题

同一个域名下挂多个系统。

• localhost/numpy 访问 numpy 对应的 teadocs 文档；
• localhost/padas 访问 padas 对应的 teadocs 文档。

server {
    listen       80;
    server_name  localhost;
 
    location /padas {
        alias   /Users/dkvirus/Documents/html/padas;
        index  index.html index.htm;
    }
 
    location /numpy{
            alias   /Users/dkvirus/Documents/html/numpy;
            index  index.html index.htm;
    }
}

teadocs.config.js 中的 theme.rootPath 用法：表示根路径，如果部署在深目录下面，这个配置项必填，不然会出现找不到资源路径的错误。

配置了根路径后，页面可以正常跳转，但是页面中的图片无法正常显示。F12 在控制台中可以看到 img 标签的 src 属性并没有添加根路径。

解决

marked 中提供一个属性 baseUrl，默认是给图片资源加前缀，实际发现只对 ![]() 语法生成的图片加上前缀，对于直接写 <img src=""/> 生成的图片不起作用。

在由 markdown 文件生成 html 时，拿到所有 img 标签，在 src 属性前面也要追加根路径 theme.rootPath，这些操作通过 str.replace() 完成 。实测有效~~

问题

Markdown不支持中文 输入中文命名的.md文件后，文章链接与文件名称就会乱码

如 中文.md 会变成 %E4%B8%AD%E6%96%87.md

问题

本地有两个 teadocs 工程，启动第一个工程：

project1 $ teadocs dev 

启动第二个工程：

project2 $ teadocs dev
<====  报错，端口已启动，请重新指定端口

端口冲突，此时可以通过指定端口启动第二个项目：

project2 $ teadocs dev -p 3100

这很麻烦。

期望

起第二个工程时，会自动检测端口是否启动，如 3000 端口已启动，会自动递增启动 3001 端口。

类似这种模式在命令行工具中很常见，提升用户体验。

问题描述

teadocs 官方文档（/lib/docs）打包之后 1.9M，其中 static 目录占了 1.8M。

static 目录大多引用的第三方库文件，这些文件除非版本升级，否则修改的次数极少。但是浏览器每次访问页面都会重复加载这些文件，造成资源浪费。

|-- font/ （128kb）  
|-- font-awesome-4.7.0/（1.3MB）  
|-- css/ （108kb）
    |-- editormd.min.css         71kb
    |-- highlight.default.min.css  （2kb）
    |-- normalize.min.css （2kb）
    |-- loading.css （21kb）          <= 开发时会修改
    |-- mobile.css（1kb）              <= 开发时会修改
    |-- monaco.css （526bit）     <= 开发时会修改
    |-- style.css （10kb）               <= 开发时会修改    
|-- js/ （232kb）
    |-- highlight.min.js （46kb）
    |-- jquery-3.3.1.min.js （87kb）
    |-- vue.min.js （86kb）       
    |-- main.js （10kb）                    <= 开发时会修改
    |-- mobile.js（3kb）                                <= 开发时会修改

上面👆统计结果，开发时可能会频繁修改的静态资源总大小 45kb （<< 1.8M）。

想法

引入 service worker 实现，在浏览器端缓存资源，下一次访问网站时提升访问速度。

只缓存第三方库和字体图标等文件，经常修改的文件不应该被缓存。

如果升级了某个库的版本，只需要修改下 service work 文件中的版本号，下一次发布网站时，捕获到 hash 码值（哪怕改了一个符号也会造成差异）不一样会自动重新缓存。

浏览器兼容问题

可以判断浏览器是否兼容 service work API，不兼容的话就不缓存，不会有任何副作用。

相关文章

• service worker 客户端缓存

问题

看完一篇文章，想看下一篇，目前唯一的操作是在左边目录树选择相应文章。在手机上阅读很不方便。

建议

每篇文章底部增加两个按钮：上一篇、下一篇。

问题

目前，tree.md 中的文章都会在网页显示出来。
实际使用中，在学习新技术时，我希望用 teadocs 记录📝笔记，于是在 tree.md 中添加了一条记录；
打包时，teadocs 会把《Typescript 笔记》这份笔记也打包出来，但此时这只是笔记，内容很杂乱；
在未整理内容之前，我希望《Typescript 笔记》只是一份草稿，打包时不应该包含这篇文章。

- [介绍](/index)
- [Typescript 笔记](/typescript)

期待

tree.md 添加符号 $，打包的时候过滤所有 $ 开头的文章。

- [介绍](/index)
- [$Typescript 笔记](/typescript)

补充

判断是开发还是生产环境，通过参数 dev 或者 build 可以得到。

• teadocs dev 阶段打包生成的文章应该包含所有文章；
• teadocs build 阶段打包生成的文章不包含 $ 开头的文章。

整个tree可否方便地转换为单个PDF？

dev 模式下监听 md 文件改动会重新 build 全部文件，我希望只 build 改动的文件，这样可以提高dev build 速度。

问题

随着 Flutter 热度升高，dart 语言用的也越来越多。
目前 teadocs 自带的 highlight.min.js 不支持 dart 语言高亮显示。

解决

https://highlightjs.org/download/ 默认只支持 34 种常见的语言高亮。
其它语言高亮可以自己勾选，然后 download。

补充

还有几种语言默认包也没有：

• Flutter 开发用到 Dart；
• Android 开发使用 gradle 包管理器，需要用到 Gradle 和 Groovy

如题，

问题描述

修改 md 文件，代码块的样式改变了。

需要手动刷新一下页面才会显示代码块样式。

目前猜测：修改代码后 websocket 推送了啥，导致样式丢失？

这个问题如果能解决，那 【优化】页面切换时记录菜单栏滚动条位置 也可以解决了。

/build文件夹下的内容可以轻松部署在gh page上，只需在该文件夹下添加一个名为_config.yml的文件，内容如下：

theme: jekyll-theme-cayman

但是每次执行teadocs build指令后，该文件就会被清除，导致需要手动重新创建该文件。是否有什么办法在build时忽略该文件，或者有更好的办法部署到github page上？

描述

每次从左边的菜单点击章节跳转之后，左边的菜单栏会自动跳转到顶部去，希望可以优化成下一个页面会记录上一次菜单的滚动条位置。

方案

部署到 web 服务器上的都是一个个 html 页面，每次点击菜单栏切换页面，页面都会重新加载，导致菜单栏滚动条会复位到最初位置。

监听菜单栏滚动事件，将滚动条的位置记录到 localStorage 中，当页面切换时，优先从 localStorage 中拿滚动条位置值，通过 scrollTop() 设置滚动条的位置。

像pandoc、nbconvert这些强大的工具可以把各种类型文档转成html, 再加上teadocs就可以快速生成一份文档手册