快速开始
你正在阅读的是PFDS的文档!(注:本文文档可能使用的并非pfds的最新版本)
PFDS 是一个基于纯前端技术构建的文档系统,无需后端服务即可快速搭建本地文档网站。适合用于项目说明、API 文档、教程指南等轻量级场景。使用简单的命令即可初始化、调试和部署文档站点。
本文档使用PFDS编写,其中绝大数页面仅使用pmd(pfds需改了Markdown语法使其更适合pfds的使用场景,简称;pmd),此文档也同时作为pfds的演示站
安装pfds
# 依赖安装
PFDS 安装前需要的依赖项 NPM
🔗 Node下载 NPM。 最好使用最新版本,因为这是我们通常会测试的版本。
# 创建项目
创建项目 [windows环境下PowerShell,而非cmd]
;通过通过 npx 直接使用: npx pfds-init@latest
# 启动开发服务器
启动开发服务器 pfds dev
# 项目编译
在控制台使用 pfds build
即可完成项目的编译,编译后的产物目录: /output
# 文档源内容演示,下面是当前页面的源代码:
# 快速开始
:::>[orange/90]
{w}
你正在阅读的是PFDS的文档!
PFDS 是一个基于纯前端技术构建的文档系统,无需后端服务即可快速搭建本地文档网站。适合用于项目说明、API 文档、教程指南等轻量级场景。使用简单的命令即可初始化、调试和部署文档站点。
本文档使用PFDS编写,其中绝大数页面仅使用pmd(pfds需改了Markdown语法使其更适合pfds的使用场景,简称;pmd),此文档也同时作为pfds的演示站
{/w}
:::
---
# 安装pfds
:::[o|100]
{w}
## 依赖安装
PFDS 安装前需要的依赖项 :red:NPM:red: 🔗 <a href="https://nodejs.org/en/download/" style="color: #da0000;">Node</a>下载 NPM。 最好使用最新版本,因为这是我们通常会测试的版本。
## 创建项目
创建项目 :red: [windows环境下PowerShell,而非cmd] :red: ;通过通过 npx 直接使用: :: npx pfds-init@latest ::
## 启动开发服务器
启动开发服务器 :: pfds dev ::
## 项目编译
在控制台使用 :: pfds build :: 即可完成项目的编译,编译后的产物目录: :: /output ::
{/w}
:::
---
pmd
配置文件
PFDS 共包含3个配置文件,分别为头部配置(head.json),路由配置(router.json),全局配置(pfds.json),本页将对他们进行详细讲解
# 头部配置文件 head.json
{
"head": [
{
"title": "快捷操作",
"children": [
{
"title": "返回上级",
"url": "../"
},
{
"title": "演示选项",
"url": "../"
}
]
},
{
"title": "GitHub",
"icon": "icon-github",
"url": "https://github.com/nanxiangxi/pfds"
}
]
}
通过这个配置文件您可以实现对与头部搜索框后部分导航的配置
json
# 路由配置文件 router.json
{
"routes": [
{
"id": "home", //专属id
"title": "快速开始", //侧栏名称
"file": "home.html" //视图文件名称
},
{
"group": "快速开始", //分组名称
"open": true, //是否展开
"items": [
{"id": "Shortcuts","title": "命令行","file": "Shortcuts.pmd"}, //菜单项
{"id": "config",title": "配置文件","file": "config.pmd"} //菜单项
]
}
]
}
注意:配置文件中必须要存在home这个id
通过这个文件你可以配置路由,id负责指定对于的页面id不可重复,title负责指定最终生成内容再右侧的名称,file负责指定views目录下对应的视图文件,
一些建议:
建议大家编写时id为对应视图名称的前缀,例如home ->home.html
视图文件后缀命名:根据页面markdown(pfds修改版,简称pmd)和html的代码量来决定,如果大量使用pmd则后缀优先命名.pmd,如果html原生代码多则使用.html
json
# 全局配置 pfds.json
{
"siteTitle": "Pfds --文档", //文档名称
"theme": "dark-1", //文档主题样式
"template": "main.html", //主模板
"initCssAutoLoad": true, //css动态加载模式
"themeToggle": false //启用双主题按钮
}
siteTitle负责控制您的文档名称,theme负责指定您要使用的主题名称...
json
# 图标配置 icon.json
{
"icons": [
{
"name": "github", //图标名称,最终对应为icon-github
"url": "data:image/svg+xml;charset=utf-8;base64,xxxxx", //图标dataurl
"width": 20, //图标宽度
"height": 20 //图标高度
}
]
}
json
视图
视图作为PFDS中的核心组件之一,主要负责展示内容和用户交互。本文档将详细介绍如何编写PFDS的视图部分,包括基础结构、动态内容显示控制等。
# 视图文件基础结构
PFDS的视图文件基于HTML编写,并通过特定的ID机制来控制不同内容的显示与隐藏。此外,PFDS引入了对部分Markdown语法的支持,使得编写更加灵活便捷。
# 视图的编写
通过router.json配置视图文件后,在views/xxx进行编写。
# 动态内容显示控制
视图切换JS:showPage('home'),参数要求:指定页面的id,例如:home
# 右侧导航
PFDS 会自动将 “< h2>”标签转化为右侧导航
视图CSS
视图中编写css十分常用,本文将介绍css的隔离和动态加载。
# CSS隔离
PFDS的css隔离通过作用域的方式实现,你可以使用内联的写法进行编写,编译时会自动对CSS进行隔离,确保视图部分的CSS仅作用于当前视图
# CSS动态加载
PFDS对于视图css的处理分两种:
当你在核心配置文件(pfds.json)设置 "initCssAutoLoad": true,
时,编译器会将css提取并生成单独的css文件,然后根据页面的不同进行动态加载
当你设置"initCssAutoLoad": flase,
这编译后的css会保持内联写法
视图JS
视图中编写js十分常用,本文将介绍JS的隔离和动态加载。
# JS隔离
pfds默认配置为内联写法,即JS代码内联在HTML中,当视图被加载时JS会执行。
# JS动态加载
PFDS对于视图JS的处理分两种:
当你在核心配置文件(pfds.json)设置 "initJsAutoLoad": true,
时,编译器会将js提取并生成单独的js文件,然后根据页面的不同进行动态加载
当你设置"initJsAutoLoad": flase,
这编译后的JS会保持内联写法
# 视图JS编写注意事项
请注意,pfds中编写js需要采用内联写法,并且< script>< /script>标签内的内容仅能作用于当前视图,如果您希望编写全局js请使 < script public>< /script>这样的写法
修改后的Mrakdown语法(pmd)
pfds需改了Markdown语法使其更适合pfds的使用场景
# 不解析内容
当前在pfsd中使用 :"*内容 *"
(英文引号+星号 内容 星号+英文引号)这样的写法,其中内容不会被pfds解析,使其可以保持原始内容显示。
"* # 不被解析的一级标题 *"
pmd
最终显示效果如下:
# 不被解析的一级标题
# 表格
| 姓名(默认) | 年龄(居左) |编号(居右)|个性(居中)|
|:------------:|:----------|---------:|---------|
| 张三 | 25 |1|一个张三|
| 李四 | 30 |2|一个李四|
完全继承markdown的写法
pmd
最终显示效果如下:
姓名(默认) |
年龄(居左) |
编号(居右) |
个性(居中) |
张三 |
25 |
1 |
一个张三 |
李四 |
30 |
2 |
一个李四 |
# 分割线
单横线分割: ---
双横线分割: ===
最终效果如下:
pmd
单分割线:
双横线分割:
# 标题
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
pmd
标题写法为: # 标题 其中 “#” 个数代表层级,最高支持6级,完全继承markdown写法,最终效果如下:
一级标题
# 二级标题
# 三级标题
四级标题
五级标题
六级标题
# 注意框
:::[o]
默认注意框
:::
:::> [red]
带有竖杠的红色注意框
:::
:::> [green/]
带有竖杠的绿色居左注意框
:::
::: [blue\90]
蓝色居右宽度为90%的注意框
:::
>(代表是否带竖线,可有可无)
颜色:ren,green,blue,orange等,需要在主题css文件定义,默认只有4种
|:居中,/居左,\居右,可有可无,默认居中
80:指定宽度,默认90
pmd
最终效果如下:
默认居中无颜色注意框
居右蓝色宽度为90%的注意框
默认居中蓝色宽度为90%的注意框
# 代码块
```javascript|90=
这是PMD的代码块,90宽度,支持复制功能
```
语言类型:javascript
|:居中,/居左,\居右,可有可无,默认居中
80:指定宽度,默认90
=:指定功能,是否支持复制,可以有可无
pmd
最终效果如下:
这是PMD的代码块,90宽度,支持复制功能
javascript
# 内联代码块
:red: console.log("Hello") :red:
reg:指定颜色,默认为红色
pmd
最终效果如下:
console.log("Hello")
# 无序列表
* 一级
** 二级
*** 三级
* 另一个一级
pmd
无序列表的语法为:* 列表名称,其中*个数代表层级,支持无限极 最终效果如下:
# 有序列表
1. 一级
1.1. 二级
1.2. 另一个二级
1.1.1. 三级
2. 另一个一级
pmd
有序列表的语法为: 数字+点 列表名称,支持无限极,最终效果如下:
- 一级
- 二级
- 三级
- 另一个二级
- 另一个一级
# 非搜索区(这个区域内的内容,不会被搜索)
{no?}内容{/no?}
pmd
若你使用html的写法,则为:
< div data-no-search>
不会被搜索的内容---写法1
< /div>
或者
< div class="no-search">
不会被搜索的内容---写法2
< /div>
html
# 富文本区(这个区域内支持换行,空格等)
{w}
这是富文本区
支持富文本,支持换行,空格等
{/w}
pmd
最终效果如下:
这是富文本区
支持富文本,支持换行,空格等
# 视图切换(点击后可有跳转到文档的其他视图)
go@about[快速开始]
pmd
最终效果如下:
安装
# 加粗文本
前方内容 **启动失败**
pmd
最终效果如下:
前方内容 启动失败