浙江龙网

  1. 首页 > 生活百科 > >

要写文档了，emmm，先写个文档工具吧——DocMarkdown

生活百科

前言之前想用Markdown来写框架文档，找来找去发现还是Jekyll的多 ， 但又感觉不是很合我的需求于是打算自己简单弄一个展示Markdown文档的网站工具 ， 要支持多版本、多语言、导航、页内导航等，并且支持Github Pages免费站点
组件选择我自己呢比较喜欢C#，恰好现在ASP.Net Core Blazor支持WebAssembly，绝大部分代码都可以用C#完成对于Markdown的分析 ， 可以使用markdig组件（有个缺点，目前它把生成Html的代码也放到了程序集里，增加了不少的程序集大?。?增加了载入时间）展示组件可以使用Blazorise，有挺多组件能用，还有几个风格能?。褂帽冉戏奖?
配置为了能提供较好的通用性，我定义了以下配置
配置文件站点目录必须包含config.json配置文件，配置文件声明了DocMarkdown该从哪里读取Markdown文档并建立目录关系 。
config.json是一个JSON格式的配置文件，以下配置是一个完整的配置文件示例 。
{"Title": "DocMarkdown","Icon": "logo.png","BaseUrl": "https://raw.githubusercontent.com/who/project","Path": "docs","Languages": [{"Name": "简体中文","Value": "zh-cn","CatalogText": "本文内容"}],"Versions": [{"Name": "DocMarkdown 1.0","Value": "1.0","Path": "main"}]}标题$.Title属性值决定了显示于左上角（默认主题）的文档标题名称 。该属性必须填写 。
图标$.Icon属性决定了显示于文档标题左侧的图标路径 。该属性可不存在或为空 。
基础地址$.BaseUrl属性决定了整个Markdown文档的路径 。该属性必须填写 ， 可以为空字符串 。当属性为空字符串或相对路径时，将使用本域名内资源 。
路径地址$.Path属性将附加于每个Markdown文档路径之前 。该属性可以不存在 。
多语言$.Languages属性用于定义文档的多语言支持 。该属性可以不存在 。属性内容必须为数组 。第一个元素将作为默认语言 。
语言名称$.Languages[0].Name属性用于显示语言名称 。该属性必须填写 。
语言值【要写文档了，emmm，先写个文档工具吧——DocMarkdown】$.Languages[0].Value属性决定了该语言的文件名称 。该属性必须填写 。属性内容将附加在Markdown文档路径扩展名之前 。例如.zh-cn 。
目录文本$.Languages[0].CatalogText属性决定了选择该语言时 ， 文档页右侧的导航目录标题 。该属性必须填写 。
多版本$.Versions属性用于定义文档的多版本支持 。该属性可以不存在 。属性内容必须为数组 。第一个元素将作为默认版本 。
版本名称$.Versions[0].Name属性用于显示版本名称 。该属性必须填写 。
版本值$.Languages[0].Value属性决定了该版本在Url上的值 。该属性必须填写 。
版本路径$.Languages[0].Path属性决定了该版本在Url上的值 。该属性必须填写 。
导航配置文档根路径必须存在nav.json，如果存在多语言，每个语言都需要一份导航配置 。以文档路径规则里的示例为例，则必须存在https://raw.githubusercontent.com/who/project/main/docs/nav.zh-cn.json导航配置文件 。
nav.json是一个JSON格式的配置文件，以下配置是一个完整的配置文件示例 。
{"简介": {"Path": "index"},"快速使用": {"Path": "quick"},"高级": {"Children": {"内容A": {"Path": "advanced/content1"},"内容B": {"Path": "advanced/content2"}}}}导航文件的内容将被解析生成树形结构展示于页面 。
节点名称$.{name}属性名称将作为导航目录的树形节点名 。属性值为对象，不能为空 。可以存在多个节点 。
节点路径$.{name}.Path属性作为该节点对应的文档路径 ， 路径为相对路径 。属性可以不存在 。不存在或为空时，只作为可折叠节点，点击不会导航至其它页面 。
节点子项$.{name}.Children属性作为该节点的子项容器，里面包含了该节点下的所有子节点内容 。属性可以不存在 。
可以组合多层树形导航目录 。
{"一级目录1": {"Path": "c1"},"一级目录2": {"Path": "c2"},"一级目录3": {"Children": {"二级目录1": {"Path": "c3/c1"},"二级目录2": {"Children": {"三级目录1": {"Path": "c3/c2/c1"},"三级目录2": {"Path": "c3/c2/c2"}}}}}}文档路径规则基于配置，DocMarkdown会将网站的路径映射至目标文档 。例如

推荐阅读


上一篇：PGL Paddle Graph Learning 关于图计算&图学习的基础知识概览：前置知识点学习

下一篇：重新整理 .net core 实践篇 ———— dotnet-dump [外篇]