Skip to content

📒 笔记 ​

字数
3693 字
阅读时间
15 分钟

小音和猫猫的知识库 ​

欢迎来到小音和猫猫的知识库 Nólëbase,这里是 📒 笔记分区

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

很高兴你对 Nólëbase 感兴趣!

背景介绍 ​

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

在继续之前,也请容许我介绍一下对项目所使用的技术和架构。

和其他的由 Hexo 驱动和生成的博客和静态网站类似,Nólëbase 其实使用了名为 VitePress 的静态生成器来驱动和生成网站,像 VitePress 这样的静态生成器支持在 Markdown 文件中使用 Vue 组件来嵌入并增强文档的阅读和使用体验。而 VitePress 和 Vue 是 Node.js 生态的一部分,他们都属于「前端技术」的一部分。

在运行和部署上,我们使用免费的 Netlify 来提供网站的托管,使用 GitHub Actions(你可以理解一个将会在每次我们将笔记和知识库内容更新到 GitHub 仓库之后会自动触发的一个自动化工作)把我们的笔记和知识库内容自动构建和部署到 Netlify 上。

等等,这和 Obsidian Publish 有什么不同 ​

好问题,作为 Obsidian 的用户,你可能会知道他们开发团队提供了一套专门用于发布 Obsidian 中的笔记的服务「Obsidian Publish」,如果你不知道也不要紧,可以把 Obsidian Publish 理解为一个可以帮助你将 Obsidian 中的笔记发布到互联网上帮助你分享和提供搜索引擎优化(SEO)的服务。

为什么不用 Obsidian Publish ​

  1. Obsidian Publish 需要付费才能使用,但是实际上对于静态网站而言,就像先前介绍的那样,我们可以白嫖一些像是 GitHub Pages,Netlify,Vercel 和 Cloudflare Pages 这样现成的基础设施帮忙托管;
  2. Obsidian Publish 部署后的静态页面是没有 Obsidian 自带的插件功能的支持的,这意味着很多作者(或者你)在本地撰写好的使用了插件支持的语法的文档在本地使用 Obsidian 渲染和预览的时候是能正常工作的,然而将会在 Obsidian Publish 部署和托管后变得不可用。这是非常关键的一个问题,很多用户(包括我在内)都非常依赖于 Obsidian 的插件生态,这样的问题现在还没有足够好的解决方案,但我们创建了名为 Nólëbase 集成 这样的项目来尝试提供一些常见的和常用的 Obsidian 插件在 VitePress 和 Vue 的环境下的替代方案,这样的替代方案虽然不能完全替代 Obsidian 插件的功能,但是可以在一定程度上提供类似的功能,你也可以关注一下;

在什么情况下你应该使用 Obsidian Publish ​

Obsidian Publish 也有它自己的优点:

  1. 寻找适合 VitePress 的 Markdown 插件是困难和复杂的,Obsidian Publish 天然支持所有 Obsidian 原生支持的语法和插件,这意味着你不需要额外的调研和试错工作就可以将你在本地使用 Obsidian 撰写的文档直接部署到互联网上;
  2. 运行和部署像是 Nólëbase 这样的静态网站对于不具备任何的代码和编程知识的作者难度大得多,但是 Obsidian Publish 不需要任何的代码和编程知识,也无需关心任何的技术细节,和 Notion 的分享一样,你只需要点击几下就可以完成部署;

所以如果你没有掌握必备的编程技能,或者你不想花时间和精力去学习和掌握这些技能,那么 Obsidian Publish 可能是一个更好的选择。

所以,也有别人在这样使用 VitePress 作为可部署的知识库吗? ​

哦,当然!

这里有一些我们在 GitHub 上发现的使用 VitePress 作为知识库的项目:

如何下载到本地 ​

废话不多说,我们开始下载的步骤吧。

如果你没有熟练掌握诸如命令行和 Git 的使用,我们在这里建议你使用 GitHub 本身提供的 下载源代码存档 功能直接从 GitHub 站点上下载打包好的压缩文件包,然后到本地解压后查看和使用。

如果你掌握了命令行和 Git 的使用,可以通过下面的命令克隆项目仓库到名为 nolebase 的目录中:

shell
git clone https://github.com/nolebase/nolebase

使用的是 Windows 吗 ​

注意

如果你使用的是 Git for Windows ,那么可能会在执行上述命令时,遇到类似这样的报错:

PowerShell
PS D:\> git clone https://github.com/nolebase/nolebase
...
error: invalid path 'x: xxx.md'
fatal: unable to checkout working tree
warning: Clone succeeded, but checkout failed.
You can inspect what was checked out with 'git status'
and retry with 'git restore --source=HEAD :/'

这是 Git for Windows 的默认配置导致的问题。

你可以在命令行窗口中输入下面的命令来解决这个问题:

PowerShell
git config --global core.protectNTFS false

如何使用、运行或者部署 ​

完成了下载了吗?很好,恭喜你已经完成了很艰难的一步!

正如先前介绍过

Nólëbase 其实使用了名为 VitePress 的静态生成器来驱动和生成网站。

而 VitePress 和 Vue 是 Node.js 生态的一部分,他们都属于「前端技术」的一部分。

因此你需要先配置一下 Node.js 和添加和管理 VitePress 和 Vue 作为底层管理依赖的工具 pnpm 。

准备工作 ​

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

  1. 安装和配置 Node.js,要校验 Node.js 是否安装成功,可以通过打开命令行窗口然后运行 node --version 和 npm --version 来查看是否会报错;
  2. 安装和配置 pnpm,要校验 pnpm 是否安装成功,可以通过打开命令行窗口然后运行 pnpm --version。
使用的是 Windows 吗 ​

注意

如果你使用的是 Windows,可以选择通过 scoop(一款在 Windows 上面向开发者可用的包管理器)来安装这些必要的工具,这样可以避免在 Windows 上面安装和配置这些工具的时候遇到的一些问题。

想要快速安装 Scoop,使用 Win + Q 打开搜索,键入「Powershell」之后点击搜索结果中的蓝色方块,然后输入下面的命令:

powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
powershell
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

使用 Win + Q 打开搜索,键入「Powershell」之后点击搜索结果中的蓝色方块,然后输入下面的命令:

shell
node --version

如果你看到了类似于 vxx.xx.xx 的版本号(比如 v21.1.0),那么恭喜你,你已经成功安装了 Node.js。

如果没有看到,那么你需要先安装 Node.js。如果采用了上面提到的 scoop,可以使用下面的命令来安装 Node.js:

shell
scoop install nodejs

注意

由于我们使用到了 sharp 这个依赖来生成图片,而 sharp 依赖需要使用到 Python,因此你也需要安装 Python。

如果采用了上面提到的 scoop,可以使用下面的命令来安装 Python:

shell
scoop install python

接下来让我们来安装 pnpm,使用下面的命令来安装 pnpm:

shell
corepack enable
shell
corepack prepare pnpm@latest --activate

首次安装完成之后需要运行一下

shell
pnpm setup

来配置 pnpm 所需要的目录,完成之后需要关掉当前的 Powershell 窗口,然后重新打开一个新的 Powershell 窗口。

差不多准备好啦,让我们前往 Nólëbase 知识库所在的目录吧,使用下面的命令来前往 Nólëbase 知识库所在的目录:

shell
cd

先多输入一个空格,然后接下来打开文件管理器,把你解压缩完成的 Nólëbase 知识库文件夹拖拽到运行窗口中,最后按下 回车 键,就可以告诉 Powershell 前往 Nólëbase 知识库所在的目录了。

使用的是 macOS 吗 ​

注意

如果你使用的是 macOS,可以选择通过 Homebrew(一款在 macOS 上面向开发者可用的包管理器)来安装这些必要的工具,这样可以避免在 macOS 上面安装和配置这些工具的时候遇到的一些问题。

想要快速安装 Homebrew,使用 command + 空格 打开「终端」应用,然后输入下面的命令:

shell
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

使用 command + 空格 打开「终端」应用,然后输入下面的命令:

shell
node --version

如果你看到了类似于 vxx.xx.xx 的版本号(比如 v21.1.0),那么恭喜你,你已经成功安装了 Node.js。

如果没有看到,那么你需要先安装 Node.js。如果采用了上面提到的 Homebrew,可以使用下面的命令来安装 Node.js:

shell
brew install node

接下来让我们来安装 pnpm,使用下面的命令来安装 pnpm:

shell
corepack enable
shell
corepack prepare pnpm@latest --activate

首次安装完成之后需要运行一下

shell
pnpm setup

来配置 pnpm 所需要的目录,完成之后需要关掉当前的终端窗口,然后重新打开一个新的终端窗口。

差不多准备好啦,让我们前往 Nólëbase 知识库所在的目录吧,使用下面的命令来前往 Nólëbase 知识库所在的目录:

shell
cd

先多输入一个空格,然后接下来打开访达,把你解压缩完成的 Nólëbase 知识库文件夹拖拽到终端窗口中,最后按下 return 键,就可以告诉终端前往 Nólëbase 知识库所在的目录了。

使用的是 Linux 吗 ​

你既然已经在使用 Linux 了,应该知道怎么做了吧?

安装依赖和运行开发服务器 ​

在倒数第二步中,我们需要安装依赖,这样 VitePress 和 Vue 就会被下载到本地的 Nólëbase 目录/文件夹下的 node_modules 目录/文件夹下了:

shell
pnpm install

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

shell
pnpm docs:dev

就像这样

shell
$ pnpm docs:dev

  vitepress v1.0.0-rc.20

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

当你看到上面的字样的时候,就可以前往本地的 http://localhost:5173 查看渲染完成的页面了:

在这个本地运行的 Nólëbase 知识库前端服务器启动的情况下,你针对所有 Markdown 文件、样式文件、配置文件的变更,都会实时响应到网页中。

如果刷新不及时或者更新有异常,也可以试试看使用 command + R (macOS 系统) Ctrl + R (Windows 和 Linux 系统)快捷键强制刷新。

构建并渲染为可部署的静态页面 ​

想要部署页面,首先先确保你已经执行过了安装依赖和运行开发服务器 的步骤,一般而言构建和渲染的时候可能遇到的问题都可以在运行开发服务器的时候发现,接下来你只需要一个简单的命令就能完成构建了:

shell
pnpm docs:build

构建完成后,渲染出来的 HTML 和各种资源将会被存储在 .vitepress/dist 目录下面,你可以通过上传 .vitepress/dist 目录来完成 Nólëbase 知识库的部署。

使用静态网站托管服务部署页面 ​

Nólëbase 知识库使用 VitePress 静态生成器来驱动和生成静态页面,因此可以部署到下列已知的优质静态网站托管服务:

NOTE

与自建单独的虚拟机并使用类似于 Nginx,或者对象存储(OSS)相比,使用上述提及的静态网站托管服务时,可以省略手动部署流程,也无需花费时间与精力维护单独的网站服务器。

让我们把精力放在写作上吧!❤️

请参照 VitePress 官方文档的部署 VitePress 站点页面文档所介绍的内容,通过主流的静态网站托管服务来部署自己的 Nólëbase 知识库。

贡献者 ​

文件历史 ​

用 撰写