Transcription
大家好，我是Christian，在这个视频里，我想向大家展示我如何记录我学到的所有东西，以及我如何编写技术文档。因为这是一个经常被忽视的话题，甚至我自己过去也曾犯过错。我曾经是一个几乎不记笔记的人，我经常只是在我的家庭实验室里安装东西，或者输入我在谷歌上找到的任何命令。但请相信我，如果你是一名IT人员，并且每天都在学习大量新知识，那么在某个时候，你需要跟踪所有这些信息，并把它们写下来。这正是我在这个视频里要做的。我想向大家展示我最喜欢的工具Obsidian，它可以帮助你组织一个个人知识库。它使用一种叫做Markdown的标准语言，所以你可以格式化文本、图片、创建表格，甚至带有语法高亮的 कोड块。但在我们开始技术文档之前，我想对今天的赞助商Teleport说几句话。Teleport是一个免费开源的访问代理，你可以用它来安全地访问你所有的IT基础设施，比如Linux服务器、数据库、Kubernetes集群、Web应用程序，甚至远程桌面。最棒的是，它也是完全免费和开源的。它有一个社区版本，你可以直接下载并在你的整个家庭实验室中运行。如果你想在你的公司中使用它，Teleport提供了许多专业的审计和单点登录功能，等等。请联系他们的团队。你会在这个视频的描述中找到他们网站的链接。[音乐]好的，在我们深入Obsidian之前，先来谈谈Markdown的一些基本知识，以及为什么我用它来记录我所有的笔记和技术文档。我知道你很有可能已经知道Markdown是什么了，但万一你不知道，让我快速总结一下。当你写一个文本文档时，Markdown是一种所谓的标记语言，你可以用它来为你的文档添加文本格式，这与你在Microsoft Word或OpenOffice中知道的类似，当你想要让文本加粗，添加标题或插入链接时。但与在程序中点击按钮直接应用格式不同，Markdown只是一个纯文本文件，你使用特定的语法来表示文本应该是什么样子。例如，如果你想在Markdown中添加一个标题，只需在该文本前面加上一个井号。如果你想让文本加粗，只需将其放在两个星号之间。或者你可以简单地使用连字符来创建一个项目列表。要将你在纯文本中创建的Markdown文件变成可见的东西，你需要使用一个程序，它将把它转换为HTML。在VS Code中，你可以直接打开一个Markdown文件，在分屏视图中，你可以实时看到它的HTML转换。就像这样简单，你可以添加更多有用的格式，这对于编写技术文档非常有用，比如图片、链接和代码块，是的，甚至带有语法高亮。所有这些都使得创建好的、可读的README文件、备用单、项目文档，甚至只是简单的笔记变得非常有用。Markdown的另一个优点，这可能是它在IT和软件文档中如此出色的关键原因，是因为它使用一种标准化的语言。许多应用程序都能理解它，并且很容易将Markdown文档导入到不同的程序中，或者将其转换为网页发布到某个地方，例如在GitHub上。你看到的所有的README文件和文档通常都用Markdown语言编写。同样，还有许多其他程序和服务理解并使用它来格式化文本。例如，在Reddit上，它也是内容的标准语言，或者Slack也在其消息中使用Markdown。所以，它确实是技术文档和网页中用于文本格式化的广泛使用的标准。而且它很容易学习，因为Markdown不像HTML那样，它只专注于最重要的格式化语法。顺便说一句，如果你对完整的Markdown语法感兴趣，我在我的GitHub页面上创建了一个新的GG文档，你可以在那里查找所有这些不同的格式。我会在描述中留下链接。如果你喜欢我的视频，请给这个视频点赞并订阅我的频道，那将非常棒，而且对YouTube算法也有很大帮助。这就是为什么我现在用Markdown写所有的文档，而不使用任何其他程序，因为它就是最好的方式。而且有很多Markdown编辑器可以用来编写Markdown文件，并在某个地方组织你的笔记或文档。我想向大家展示我最喜欢的程序，它有一些非常高级的功能，远远超出了格式化。它叫做Obsidian，在我看来，这是目前最好的Markdown编辑器。许多人把它当作所谓的“第二大脑”，这意味着一个关于你所知道的一切的知识库。所以它不像VS Code那样只是一个方便的Markdown编辑器，它还可以帮助你通过过滤器和搜索功能来组织文档。它还支持标签、反向链接等等，这真的很令人印象深刻。而且最棒的是，它是免费的，你可以在所有系统上使用它：Windows、Linux和Mac OS。要开始使用它，你需要创建一个Vault。这就像一个存储你的Markdown文件的仓库。这里很棒的是，你可以直接打开你电脑上的一个简单文件夹并将其用作Vault。所以，如果你已经有一个从另一台机器复制过来的现有项目，或者一个你克隆下来的Git仓库，你可以直接打开它。但如果你是全新开始，你也可以创建一个新的Vault，给它一个名字，并在你的硬盘上设置一个位置。Obsidian使用的所有Markdown文档都只是这个文件夹里的纯文本文件。Vault还存储了所有的配置数据、插件，以及你在Obsidian本身中做的任何更改，都在一个.obsidian目录中。所以它可以为每个Vault配置不同的设置。要备份所有东西，你只需复制整个文件夹，然后所有设置、所有文件，一切都在那里。另外，Obsidian还提供另一项服务，叫做Obsidian Sync，它可以自动在不同设备之间同步你的Vault。不过，这是一个付费选项，而且说实话并不便宜，大约每月10美元。但因为Obsidian Vault只是文件系统中的基本文件夹，你当然也可以使用其他工具来同步和备份你的Vault。我已经提到了Git，我就是这样做的，但也有其他解决方案，比如在Google Drive或OneDrive文件夹上打开一个Vault，这些也是可行的。我唯一认为Obsidian Sync真正有用的时候，是当你需要在手机上使用它的时候，因为在那里同步文件夹有时会有点困难。不幸的是，Obsidian的移动版不支持OneDrive或Google Drive。但如果你和我一样，主要使用Obsidian来记录IT项目的技术文档或笔记，你可能不会在手机上做这些事情。所以，在我看来，将Obsidian与Git结合作为存储是最好的方式。例如，你可以在GitHub上创建一个免费的仓库，甚至可以是私有的，然后将其克隆到你的PC上，然后在Obsidian中将其打开为一个文件夹。我就是这样做的，目前我有三个不同的Git仓库作为Vault在使用。所以我建议不要在Obsidian中添加太多Vault，因为在它们之间切换对我来说有点烦人。最好是只有一个或两个Vault，然后你仍然可以在子文件夹中组织所有文档。我可以通过打开我的备用单Vault来最好地展示这一点。这是一个Git仓库，我在这里收集了我家庭实验室项目中学到的所有东西的知识库。我强烈建议建立这样一个知识库，尤其是在IT领域工作时，因为你会遇到很多你无法全部记住的新东西。例如，当我学习到一个关于CubeCDL这样的工具的新知识时，我会写下一段简短的文字来解释某些基本知识，或者列出经常使用的命令。我遵循的一些原则或模式。写这样的文档时，我首先描述它是什么，然后我创建带有标题和副标题的单独部分，比如安装、简短解释、命令参考，任何对这个文档有意义的内容。在Markdown中很酷的是，如果你有任何命令或代码模板，你可以将它们放在代码块中。要开始一个代码块，只需输入三个单引号，然后是你正在编写命令的语言。所以，如果你写Python指令，只需输入Python。如果是Shell命令，只需使用bash或Powershell，取决于你使用的是哪种。用三个单引号关闭这个代码块。现在，你对整个指令都有了语法高亮。这对于描述YAML文件，比如这个，或者SQL命令，比如这个，非常酷且有用。你也可以直接点击代码块右上角的按钮来复制代码块。顺便说一句，我真的无法表达我有多喜欢这个功能。并且要记住，你可以直接将这个文档上传到任何地方，例如GitHub或任何其他程序或网站，因为这是一个Markdown语言，它是一个标准，你可以轻松地将其转换为HTML，没有任何问题，而且你拥有相同的语法高亮和其他一切，而无需更改文档的格式。但这还不是全部，当然。Markdown也支持添加URL。所以，如果你想添加一个链接到更详细的说明页面或类似的东西，你只需用方括号开始，输入链接文本，然后在普通括号中输入URL。现在它就变成了一个链接。或者，如果你想插入一张图片，因为你想添加一个来自Draw.io的图表或其他什么，将其复制到你的Vault中，然后在说明中，只需以感叹号开始，在方括号中放入alt文本，或者留空，然后在普通括号中输入图片的URL。这可以是一个相对路径，在这个文件结构中。然后你就得到了一张图片。这就是你开始用Markdown编写文档或笔记的方式。说实话，这是所有Markdown编辑器都可以做到的，它们不仅仅是Obsidian。但让我展示一些Obsidian真正脱颖而出的地方。因为当你建立这样一个知识库，比如我的备用单仓库，或者任何类型的笔记系统时，组织这些东西是一个很大的挑战，尤其是在你的文档不断增长的时候，因为你当然想快速找到东西。为了实现这一点，我设计了一个系统，将类似的主题放在文件夹里。比如，我有一个关于应用程序的文件夹，一个关于技术，比如云、数据库、Docker和Kubernetes，或者这里是我的Linux文件，我的Mac OS文件，网络工具，Windows，任何有意义的放在一起的东西。但你也可以这样做，这不是Markdown的标准，这真的是Obsidian的一个功能。你用反向链接将这些主题联系起来。例如，这里有一个关于Traefik的文档，这是一个用于Docker和Kubernetes的反向代理。在描述中，我添加了两个链接到其他文档，解释了这些术语的含义。这是通过添加双括号并链接另一个文档的名称来完成的。例如，如果你想去Docker，你可以点击它，它会带我到Docker的Markdown文档。或者这里我有一个关于k3s的文档，一个轻量级的Kubernetes实现，我将不同的安装说明分成了其他的Markdown文档。Obsidian还有一个非常好的图表，就像你Vault中所有文档的地图，由点表示，它连接了所有有反向链接的文档。这不仅看起来非常酷，而且还有助于你可视化你的知识库或你正在记录的任何内容。它有助于你保持对一切的概览，并且可以找到你可能想添加更多内容的部分。例如，就像我这里的Linux部分，有几个点连接在一起，但我知道还有很多我需要填补的内容。你也可以通过添加一个井号来使用标签，然后你可以用查询来搜索一个特定的标签，它会显示你所有的文档。不过，我并不经常在我的备用单中使用它，因为我主要只使用反向链接和文件夹，对我来说，这足以找到一切。但实际上我做什么并不重要。所以，即使我展示了我的文档风格，你也应该找到你自己的组织和建立这样一个知识库的风格。主要目标是再次更容易地找到说明并查找东西。相信我，建立这样一个知识库需要很长很长的时间。而且有时也很难弄清楚要写什么，什么可以跳过，因为你并不总是需要对每一个程序或命令进行完整的解释。在这种情况下，我只是在Markdown文档中添加一个链接到官方文档或网站。但一些通用说明，比如指南、有用的命令或配置模板，我认为这些是值得写下来的。所以不要写太多东西，专注于你需要的查找的要点，并添加一两句话的解释，也许链接到相关的文档，就这样。这就是我建立我的知识库或GG文档的方式。如果你现在想，好吧，Christian，这都很好，但工作量太大了，我很懒。这就是为什么我把它们分享给你们，你们可以在GitHub上找到这个仓库。我会在下面的描述中留下链接。欢迎你克隆这个仓库到你的机器上，用于快速参考你可能需要的东西。如果你喜欢，我很乐意你做出贡献。如果你想一起在这个备用单仓库上工作，那将是太棒了，因为我有时没有时间写下每一个命令。我只写下我遇到的绝大多数东西。但为了让它成为一个很好的文档，让我们一起在这里构建一些东西。好的，我得停止为自己的东西做广告了。欢迎随意使用它，如果你做出贡献，我会很高兴。让我再向你展示一个我称之为“docs”的仓库。这是一个我用于家庭实验室内部项目文档的私有Git仓库。在这里，我添加了诸如IP地址管理之类的内容。我只是写下一个表格，说明我的网络中有哪些设备拥有静态IP地址，或者我写下我部署的服务，在哪里部署了它们，以及访问它们的URL。这总是一个好主意，无论何时你在处理IT基础设施，即使是在家庭实验室里，在某个时候它都会变得异常复杂。所以写下所有这些东西，比如你的网络是如何组织的，随着你的家庭实验室的增长，变得越来越有用。不要在这里写任何凭据，这是关键。你永远不想在任何技术文档中包含用户名或密码。如果你这样做，我个人会来找你并惩罚你。但你当然可以写下任何关于你的IT基础设施的可发现的东西，比如IP地址、机器等等。当你用管道分隔列时，你可以使用Markdown中的表格，第一行总是标题。在标题和行之间，输入与标题相同数量的列，但用连字符填充。然后你就可以开始添加你的行了。是的，这就是你如何在Markdown中构建一个表格。你可能会觉得这有点笨拙。在Markdown中编辑表格并不真正有趣。有些人甚至可能更喜欢使用Excel表格。但在这里，Obsidian将帮助我们，因为它支持插件，这为你打开了一个全新的世界。有许多由Obsidian社区编写的插件可以增强这个程序的功能。在设置菜单中，你可以调整一般的东西，比如外观、字体等等，有两个重要的选项卡用于插件：核心插件，这些来自Obsidian团队本身；以及社区插件，这些是未经测试的插件，任何人都可以发布。所以它们并没有真正经过社区的审核，但你可以查看总安装量，这通常是使用它们的人数以及插件是否正常工作的指标。有一个特定的插件，也是最受欢迎的，叫做Advanced Tables。一旦你安装并启用它，它就会创建一个新的菜单项，你可以在其中切换这个插件的工具栏。这里有一些非常有用的表格处理功能，比如添加和删除行、列，上下移动条目。这些是你从类似电子表格的东西中知道的功能。这显然不会让Obsidian成为Excel的竞争对手，但它可以为你节省大量处理表格的时间。同样，还有许多其他插件可以增强Obsidian。有插件可以帮助你在Obsidian中进行日常计划，是的，进行时间跟踪，或者有一个每日笔记计划器，甚至一个看板。有一个插件可以实现。你可以看到，可能性是无穷无尽的。不过，我必须说，我并不是这样使用Obsidian的。我实际上并不使用很多社区插件，因为我认为有时有更好的工具来完成这些社区插件试图做的事情。对我来说，Obsidian无疑是最好的Markdown编辑器。我用它来记录我所有的笔记和IT及软件项目的技术文档。而在这方面，它绝对是最好的工具。但当然，这完全取决于你如何使用它。也许Obsidian完美地融入了你的日常计划或时间跟踪工作流程，我不知道。而这正是我如此喜欢Obsidian的原因。它并不试图成为开箱即用的全能工具。相反，它专注于重要的事情，并让你能够编写自己的插件和自定义，使这个工具成为你想要的任何东西。我相信你们中有很多人想尝试一下，看看如何将其用于自己的组织和笔记记录，或者技术文档。我希望我给了你一些灵感。现在，我真的很想听听你们的看法。你们对Obsidian有什么看法？你们用什么工具来做笔记或文档？或者，如果这是你们第一次考虑做笔记？无论如何，请给我留言，我真的很想听听你们的想法。一如既往，感谢大家的观看。非常感谢我的Patreon赞助商们，你们太棒了，极大地帮助我制作这些视频。希望你们都喜欢，我们下期再见。保重，再见。