Skip to content

Commit 11d7fe0

Browse files
committed
docs: 添加更为详细的指南信息
Signed-off-by: Neko Ayaka <neko@ayaka.moe>
1 parent 398d1f5 commit 11d7fe0

2 files changed

Lines changed: 224 additions & 15 deletions

File tree

README.md

Lines changed: 80 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -24,69 +24,135 @@
2424
- 🗃 由 Obsidian 驱动:
2525
- 强大的知识库管理工具,支持花样繁多的插件和拓展,让知识管理变得更加简单。
2626

27-
## 想要自己部署和在本地启动强大的 Nólëbase 知识库?
27+
## 想要自己部署和在本地启动强大的 Nólëbase 知识库,或者自己拥有一份
2828

2929
很高兴你对 [Nólëbase](https://nolebase.ayaka.io) 感兴趣!
3030

31-
首先 [Nólëbase](https://nolebase.ayaka.io) 是完全可以在本地无网络环境的情况下使用的!你可以使用 [Obsidian](https://obsidian.md)[Logseq](https://logseq.com/) 这样的知识库软件打开,也可以用 [Typora](https://typora.io/) 这样的 Markdown 编辑器打开进行浏览和编辑,这意味着即便你不具备任何的编程技能,也可以使用或者借鉴我们的知识库分类和组织方法。
31+
### 背景介绍
3232

33-
### 如何下载到本地
33+
首先 [Nólëbase](https://nolebase.ayaka.io) 是完全可以在本地无网络环境的情况下使用的!你可以在跟随[如何下载到本地](#如何下载到本地)的指引下载或者克隆之后使用 [Obsidian](https://obsidian.md)[Logseq](https://logseq.com/) 这样的知识库软件打开,也可以用 [Typora](https://typora.io/) 这样的 Markdown 编辑器打开进行浏览和编辑,这意味着即便你不具备任何的编程技能,也可以使用或者借鉴我们的知识库分类和组织方法。
3434

35-
如果你没有熟练掌握诸如命令行和 [Git](https://git-scm.com/)的使用,我们在这里建议你使用 [GitHub](https://github.com) 本身提供的 [下载源代码存档](https://docs.github.com/zh/repositories/working-with-files/using-files/downloading-source-code-archives) 功能直接从 [GitHub](https://github.com) 站点上下载打包好的压缩文件包,然后到本地解压后查看和使用。
35+
在继续之前,也请容许我介绍一下对项目所使用的技术和架构。
36+
37+
和其他的由 [Hexo](https://hexo.io) 驱动和生成的博客和静态网站类似,[Nólëbase](https://nolebase.ayaka.io) 其实使用了名为 [VitePress](https://vitepress.dev) 的静态生成器来驱动和生成网站,像 [VitePress](https://vitepress.dev) 这样的静态生成器支持在 Markdown 文件中使用 [Vue](https://vuejs.org/) 组件来嵌入并增强文档的阅读和使用体验。而 [VitePress](https://vitepress.dev)[Vue](https://vuejs.org/)[Node.js](https://nodejs.org/en) 生态的一部分,他们都属于「前端技术」的一部分。
38+
39+
在运行和部署上,我们使用免费的 [Netlify](https://www.netlify.com/) 来提供网站的托管,使用 [GitHub Actions](https://github.com/features/actions)(你可以理解一个将会在每次我们将笔记和知识库内容更新到 GitHub 仓库之后会自动触发的一个自动化工作)把我们的笔记和知识库内容自动构建和部署到 [Netlify](https://www.netlify.com/) 上。
40+
41+
### 等等,这和 [Obsidian Publish](https://obsidian.md/publish) 有什么不同
42+
43+
好问题,作为 [Obsidian](https://obsidian.md) 的用户,你可能会知道他们开发团队提供了一套专门用于发布 [Obsidian](https://obsidian.md) 中的笔记的服务「[Obsidian Publish](https://obsidian.md/publish)」,如果你不知道也不要紧,可以把 [Obsidian Publish](https://obsidian.md/publish) 理解为一个可以帮助你将 [Obsidian](https://obsidian.md) 中的笔记发布到互联网上帮助你分享和提供搜索引擎优化(SEO)的服务。
44+
45+
#### 为什么不用 [Obsidian Publish](https://obsidian.md/publish)
46+
47+
1. [Obsidian Publish](https://obsidian.md/publish) 需要付费才能使用,但是实际上对于静态网站而言,就像先前介绍的那样,我们可以白嫖一些像是 [GitHub Pages](https://pages.github.com/)[Netlify](https://www.netlify.com/)[Vercel](https://vercel.com/)[Cloudflare Pages](https://pages.cloudflare.com/) 这样现成的基础设施帮忙托管;
48+
2. [Obsidian Publish](https://obsidian.md/publish) 部署后的静态页面是没有 [Obsidian](https://obsidian.md) 自带的插件功能的支持的,这意味着很多作者(或者你)在本地撰写好的使用了插件支持的语法的文档在本地使用 [Obsidian](https://obsidian.md) 渲染和预览的时候是能正常工作的,然而将会在 [Obsidian Publish](https://obsidian.md/publish) 部署和托管后变得不可用。这是非常关键的一个问题,很多用户(包括我在内)都非常依赖于 [Obsidian](https://obsidian.md) 的插件生态,这样的问题现在还没有足够好的解决方案,但我们创建了名为 [Nólëbase 集成](https://github.com/nolebase/integrations) 这样的项目来尝试提供一些常见的和常用的 [Obsidian](https://obsidian.md) 插件在 [VitePress](https://vitepress.dev) 和 [Vue](https://vuejs.org/) 的环境下的替代方案,这样的替代方案虽然不能完全替代 [Obsidian](https://obsidian.md) 插件的功能,但是可以在一定程度上提供类似的功能,你也可以关注一下;
49+
50+
#### 在什么情况下你应该使用 [Obsidian Publish](https://obsidian.md/publish)
51+
52+
1. 寻找适合 [VitePress](https://vitepress.dev) 的 Markdown 插件是困难和复杂的,[Obsidian Publish](https://obsidian.md/publish) 天然支持所有 [Obsidian](https://obsidian.md) 原生支持的语法和插件,这意味着你不需要额外的调研和试错工作就可以将你在本地使用 [Obsidian](https://obsidian.md) 撰写的文档直接部署到互联网上;
53+
2. 运行和部署像是 [Nólëbase](https://nolebase.ayaka.io) 这样的静态网站对于不具备任何的代码和编程知识的作者难度大得多,但是 [Obsidian Publish](https://obsidian.md/publish) 不需要任何的代码和编程知识,也无需关心任何的技术细节,和 Notion 的分享一样,你只需要点击几下就可以完成部署;
54+
55+
### 所以,也有别人在这样使用 [VitePress](https://vitepress.dev) 作为可部署的知识库吗?
56+
57+
> 等等,有别人在这样使用 [VitePress](https://vitepress.dev) 作为知识库吗?
58+
59+
哦,当然!
60+
61+
这里有一些我们在 GitHub 上发现的使用 VitePress 作为知识库的项目:
62+
63+
- [Charles7c/charles7c.github.io:基于 VitePress 构建的个人知识库/博客。](https://github.com/Charles7c/charles7c.github.io)
64+
65+
### 如何下载到本地
66+
67+
废话不多说,我们开始下载的步骤吧。
68+
69+
如果你没有熟练掌握诸如命令行和 [Git](https://git-scm.com/) 的使用,我们在这里建议你使用 [GitHub](https://github.com) 本身提供的 [下载源代码存档](https://docs.github.com/zh/repositories/working-with-files/using-files/downloading-source-code-archives) 功能直接从 [GitHub](https://github.com) 站点上下载打包好的压缩文件包,然后到本地解压后查看和使用。
3670

3771
如果你掌握了命令行和 [Git](https://git-scm.com/) 的使用,可以通过下面的命令克隆项目仓库到名为 `nolebase` 的目录中:
3872

3973
```shell
4074
git clone https://github.com/nolebase/nolebase
4175
```
4276

43-
### 如何使用、运行或者部署
77+
### 如何使用、运行或者部署
4478

45-
很好,恭喜你已经完成了 [Nólëbase](https://nolebase.ayaka.io) 知识库的下载
79+
完成了下载了吗?很好,恭喜你已经完成了很艰难的一步
4680

47-
#### 背景介绍
81+
正如先前介绍过
4882

49-
在继续之前,请容许我对项目进行一些基本的技术和架构的介绍。
83+
> [Nólëbase](https://nolebase.ayaka.io) 其实使用了名为 [VitePress](https://vitepress.dev) 的静态生成器来驱动和生成网站。
84+
>
85+
> [VitePress](https://vitepress.dev)[Vue](https://vuejs.org/)[Node.js](https://nodejs.org/en) 生态的一部分,他们都属于「前端技术」的一部分。
5086
51-
和其他的由 [Hexo](https://hexo.io) 驱动和生成的博客和静态网站类似,[Nólëbase](https://nolebase.ayaka.io) 其实也使用了名为 [VitePress](https://vitepress.dev) 的静态生成器来驱动和生成网站,像 [VitePress](https://vitepress.dev) 这样的静态生成器支持在 Markdown 文件中使用 [Vue](https://vuejs.org/) 组件来嵌入并增强文档的阅读和使用体验。而 [VitePress](https://vitepress.dev)[Vue](https://vuejs.org/)[Node.js](https://nodejs.org/en) 生态的一部分,你需要先配置一下 [Node.js](https://nodejs.org/en) 和添加和管理 [VitePress](https://vitepress.dev)[Vue](https://vuejs.org/) 作为底层管理依赖的工具 [pnpm](https://pnpm.io/)
87+
因此你需要先配置一下 [Node.js](https://nodejs.org/en) 和添加和管理 [VitePress](https://vitepress.dev)[Vue](https://vuejs.org/) 作为底层管理依赖的工具 [pnpm](https://pnpm.io/)
5288

5389
#### 准备工作
5490

5591
所以你在继续下面的步骤之前,需要完成另外的两件事情:
5692

5793
1. 安装和配置 [Node.js](https://nodejs.org/en),要校验 Node.js 是否安装成功,可以通过打开命令行窗口然后运行 `node --version``npm --version` 来查看是否会报错
58-
2. 安装和配置 [pnpm],要校验 pnpm 是否安装成功,可以通过打开命令行窗口然后运行 `pnpm --version`
94+
2. 安装和配置 [pnpm](https://pnpm.io/),要校验 pnpm 是否安装成功,可以通过打开命令行窗口然后运行 `pnpm --version`
5995

60-
准备好之后,使用下面的命令前往下载好的 Nólëbase 知识库所在的目录吧:
96+
准备好之后,使用下面的命令将命令行窗口指向下载好的 Nólëbase 知识库所在的目录吧:
6197

6298
```shell
6399
cd nolebase
64100
```
65101

102+
不会命令行?不要紧,跟着下面的步骤来吧。
103+
104+
##### 使用的是 macOS 吗
105+
106+
使用 <kbd data-keyboard-key="macos-command">Command</kbd> + <kbd>空格</kbd> 打开「终端」应用,然后输入下面的命令:
107+
108+
```shell
109+
cd
110+
```
111+
112+
先多输入一个空格,然后接下来打开访达,把你解压缩完成的 Nólëbase 知识库文件夹拖拽到终端窗口中,最后按下 <kbd>return</kbd> 键,就可以告诉终端前往 Nólëbase 知识库所在的目录了。
113+
114+
##### 使用的是 Windows 吗
115+
116+
使用 <kbd>Win</kbd> + <kbd>Q</kbd> 打开搜索,键入「Powershell」之后点击搜索结果中的蓝色方块,然后输入下面的命令:
117+
118+
```shell
119+
cd
120+
```
121+
122+
先多输入一个空格,然后接下来打开文件管理器,把你解压缩完成的 Nólëbase 知识库文件夹拖拽到运行窗口中,最后按下 <kbd>回车</kbd> 键,就可以告诉 Powershell 前往 Nólëbase 知识库所在的目录了。
123+
124+
##### 使用的是 Linux 吗
125+
126+
你既然已经在使用 Linux 了,应该知道怎么做了吧?
127+
66128
#### 安装依赖和运行开发服务器
67129

68-
然后我们需要安装依赖,把之前提及的 [VitePress](https://vitepress.dev)[Vue](https://vuejs.org/) 添加到本地
130+
在倒数第二步中,我们需要安装依赖,这样 [VitePress](https://vitepress.dev)[Vue](https://vuejs.org/) 就会被下载到本地的 [Nólëbase](https://nolebase.ayaka.io) 目录/文件夹下的 `node_modules` 目录下了
69131

70132
```shell
71133
pnpm install
72134
```
73135

74-
接下来你可以直接运行下面的命令开启一个本地运行的 Nólëbase 知识库前端服务器,通常而言我们称之为开发服务器,在本地直接访问渲染完成的页面
136+
接下来你可以直接运行下面的命令开启一个本地运行的 Nólëbase 知识库前端服务器,通常而言我们称之为「开发服务器」,用这个服务器,可以通过浏览器在本地直接访问渲染完成的页面
75137

76138
```shell
77139
pnpm docs:dev
78140
```
79141

80-
当你看到下面的字样的时候,就可以前往本地的 [http://localhost:5173](http://localhost:5173) 查看渲染完成的页面了:
142+
就像这样
81143

82144
```shell
145+
$ pnpm docs:dev
146+
83147
vitepress v1.0.0-rc.20
84148

85149
➜ Local: http://localhost:5173/
86150
➜ Network: use --host to expose
87151
➜ press h to show help
88152
```
89153

154+
当你看到上面的字样的时候,就可以前往本地的 [http://localhost:5173](http://localhost:5173) 查看渲染完成的页面了:
155+
90156
在这个本地运行的 Nólëbase 知识库前端服务器启动的情况下,你针对所有 Markdown 文件、样式文件、配置文件的变更,都会实时响应到网页中。
91157

92158
如果刷新不及时或者更新有异常,也可以试试看使用 <kbd data-keyboard-key="macos-command">Command</kbd> + <kbd>R</kbd> (macOS 系统) <kbd>Ctrl</kbd> + <kbd>R</kbd> (Windows 和 Linux 系统)快捷键强制刷新。

0 commit comments

Comments
 (0)