Move vscode2vlab to tutorial/, adjust navigation

Author: iBug

docs/vscode2vlab.md renamed to docs/tutorial/vscode2vlab.md

@@ -10,19 +10,19 @@ icon: material/transit-connection-variant
 
 在虚拟机的桌面上，最上面**应用程序**中的 **Vlab 实验软件**里可找到预先安装的的 Vivado，点击进入 Vivado。这里请大家选择 2019.1 版本，不要选择 2016.3 的旧版本。2023.1 版本的 Vivado 虽然更便捷，但可能引起内存不足的警告，因此请大家酌情使用。
 
-![vlab experiment tools](images/vscode2vlab/vivado1.png)
+![vlab experiment tools](../images/vscode2vlab/vivado1.png)
 
 进入 Vivado 后，点击 Create Project:
 
-![Create Project](images/vscode2vlab/vivado2.png)
+![Create Project](../images/vscode2vlab/vivado2.png)
 
 然后点击 Next:
 
-![Next](images/vscode2vlab/vivado3.png)
+![Next](../images/vscode2vlab/vivado3.png)
 
 在这个界面，你可以设置工程文件的名称和路径：
 
-![Name Path](images/vscode2vlab/vivado4.png)
+![Name Path](../images/vscode2vlab/vivado4.png)
 
 随后一路 Next，直到遇到“选择开发板型号”的界面。搜索我们使用的开发板，型号为 `xc7a100tcsg324-1`，点击选择最下面的开发板。
 
@@ -32,25 +32,25 @@ icon: material/transit-connection-variant
 
     若课程安排有所调整，请以实际课程要求开发板型号为准。
 
-![ChooseModel](images/vscode2vlab/vivado5.png)
+![ChooseModel](../images/vscode2vlab/vivado5.png)
 
 完成后，我们就成功新建了一个工程项目，可以看到如下界面：
 
-![Finish](images/vscode2vlab/vivado6.png)
+![Finish](../images/vscode2vlab/vivado6.png)
 
 ### 2. 新建设计文件
 
 新建工程项目后，里面还没有我们的设计文件，接下来我们要为工程项目新建自己的设计文件。
 
 在界面左侧可以找到 Add Sources，点击它：
 
-![Add Sources](images/vscode2vlab/vivado7.png)
+![Add Sources](../images/vscode2vlab/vivado7.png)
 
 接下来我们开始新建设计文件，点击 Next，选择 Create File:
 
-![Next](images/vscode2vlab/vivado8.png)
+![Next](../images/vscode2vlab/vivado8.png)
 
-![Create File](images/vscode2vlab/vivado9.png)
+![Create File](../images/vscode2vlab/vivado9.png)
 
 ??? question "如何把别处的源代码加入此工程项目？"
 
@@ -62,11 +62,11 @@ icon: material/transit-connection-variant
 
 我们可以自行设置新建文件的名称：
 
-![Filename](images/vscode2vlab/vivado10.png)
+![Filename](../images/vscode2vlab/vivado10.png)
 
 这样，我们就完成了设计文件的新建。双击文件就可以在编辑器中编辑它了。
 
-![Finish](images/vscode2vlab/vivado11.png)
+![Finish](../images/vscode2vlab/vivado11.png)
 
 ## 本地安装并配置 VSCode {#installvs}
 
@@ -78,23 +78,23 @@ Visual Studio Code 是一款由微软开发的免费、轻量级且可扩展的
 
 ### 1. 安装 VSCode
 
-进入 VSCode 的[官方网站](https://code.visualstudio.com/)，点击 Download for Windows 下载。下载完成后打开可执行文件。在**选择附加任务**时建议全部勾选，特别是**添加到 PATH** 要勾选，否则后续还要自己将其添加到环境变量。
+进入 VSCode 的[官方网站](../https://code.visualstudio.com/)，点击 Download for Windows 下载。下载完成后打开可执行文件。在**选择附加任务**时建议全部勾选，特别是**添加到 PATH** 要勾选，否则后续还要自己将其添加到环境变量。
 
 !!! info "注意"
 
     为了 VSCode 使用的稳定性，安装路径不要包含中文。下面要讲的 ctags 和 iverilog 同理，安装路径也要避免中文。
 
-![Add to path](images/vscode2vlab/vscode1.png)
+![Add to path](../images/vscode2vlab/vscode1.png)
 
 在我们完成了 VSCode 的安装后，第一次打开时界面是纯英文，看起来不是很方便。对此我们可以找到左侧的 **Extensions** 点开，搜索 Chinese，安装第一个“中文（简体）”然后重启 VSCode 即可汉化 VSCode。
 
-![Chinese](images/vscode2vlab/vscode2.png)
+![Chinese](../images/vscode2vlab/vscode2.png)
 
 ### 2. 安装 Verilog-HDL/SystemVerilog 插件
 
 在汉化 VSCode 后，想必大家已经会在 VSCode 中搜索并安装插件了。对于 Verilog 的开发，我们需要安装 **Verilog-HDL/SystemVerilog** 插件。
 
-![Verilog-HDL](images/vscode2vlab/vscode3.png)
+![Verilog-HDL](../images/vscode2vlab/vscode3.png)
 
 这个插件提供了 Verilog 开发的大多数基础功能，包括：
 
@@ -115,15 +115,15 @@ Visual Studio Code 是一款由微软开发的免费、轻量级且可扩展的
 
     **Linter** 是自动检查源代码中是否存在编程和样式错误的工具。对于 Verilog 的 linter 当然不止一种，本教程中使用的是 iverilog。除此之外还有 xvlog 和 Verilator，但 xvlog 来自于 Vivado，你需要在电脑本地安装 Vivado 才有 xvlog。而 Verilator 则是面向 Linux 平台开发的，截至目前使用官网方法在 Windows 平台上编译的 Verilator 都无法配合 VSCode 完成代码检查，需要在子系统 WSL 中安装并运行 Verilator，这里不再介绍具体步骤。
 
-我们进入 iverilog 的[下载网站](https://bleyer.org/icarus/)，在 Download 中下载最新版本即可。安装时在 Select Components 界面全部勾选，然后勾选可执行文件所在文件夹加入用户路径。
+我们进入 iverilog 的[下载网站](../https://bleyer.org/icarus/)，在 Download 中下载最新版本即可。安装时在 Select Components 界面全部勾选，然后勾选可执行文件所在文件夹加入用户路径。
 
-![iverilog GTKWave](images/vscode2vlab/vscode4.png)
+![iverilog GTKWave](../images/vscode2vlab/vscode4.png)
 
-![iverilog Path](images/vscode2vlab/vscode5.png)
+![iverilog Path](../images/vscode2vlab/vscode5.png)
 
 安装后将 iverilog.exe 和 gtkwave.exe 所在文件夹的路径复制加入用户环境变量。
 
-![iverilog Environment](images/vscode2vlab/vscode6.png)
+![iverilog Environment](../images/vscode2vlab/vscode6.png)
 
 !!! question "如何添加环境变量"
 
@@ -157,11 +157,11 @@ gtkwave
 
 弹出这个软件则配置成功。
 
-![gtkwave](images/vscode2vlab/vscode7.png)
+![gtkwave](../images/vscode2vlab/vscode7.png)
 
-接下来我们进入[下载页面](https://github.com/universal-ctags/ctags-win32/releases)安装 **ctags**，可选择最新版本进入下载。
+接下来我们进入[下载页面](../https://github.com/universal-ctags/ctags-win32/releases)安装 **ctags**，可选择最新版本进入下载。
 
-![ctags](images/vscode2vlab/vscode8.png)
+![ctags](../images/vscode2vlab/vscode8.png)
 
 安装后同样将 ctags.exe 所在文件夹路径复制加入环境变量。
 
@@ -179,19 +179,19 @@ ctags --version
 
 按下面的设置配置 ctags，将 linter 选择为 iverilog，并在 iverilog 的 Argument 一栏中加入 -i 参数。
 
-![Extension Config](images/vscode2vlab/vscode9.png)
+![Extension Config](../images/vscode2vlab/vscode9.png)
 
-![Extension Config](images/vscode2vlab/vscode10.png)
+![Extension Config](../images/vscode2vlab/vscode10.png)
 
-![Extension Config](images/vscode2vlab/vscode11.png)
+![Extension Config](../images/vscode2vlab/vscode11.png)
 
 !!! tip "关于配置的说明"
 
     由于在安装 ctags 时已经将其加入到了环境变量，所以这里只需填入 ctags 即可。关于 `-i` 参数，是因为在实例化模块时 iverilog 会报错 "Unknown module type"，添加 `-i` 参数可以避免这种不合理的报错。
 
 这样我们就可以在 VSCode 中进行 Verilog 的开发了！
 
-![verilog](images/vscode2vlab/vscode12.png)
+![verilog](../images/vscode2vlab/vscode12.png)
 
 !!! info "提示"
 
@@ -204,9 +204,10 @@ Windows 用户应使用以下说明来安装和配置 OpenSSH。
 
 在命令行中输入 `ssh`，若输出以下信息则已经安装，可跳过安装步骤。
 
-![ssh](images/vscode2vlab/SSH1.png)
+![ssh](../images/vscode2vlab/SSH1.png)
 
 !!! info "Windows 10 和 Windows 11"
+
     Windows 10 和 Windows 11 版本的 OpenSSH 安装有所区别，请按对应的版本进行操作。
 
 在安装时，
@@ -235,20 +236,21 @@ ssh [email protected]
 
     `Vlab username` 是你的学号（或工号），在登录虚拟机管理页面后可以在右上角看到。
 
-    `Vlab password` 是 Vlab 平台的登录密码。[还没设置？](web.md#change-password)
+    `Vlab password` 是 Vlab 平台的登录密码。[还没设置？](../web.md#change-password)
+
+!!! question "Vlab 的登录用户名？"
 
-!!! question "关于 Vlab 的登录用户？"
-    这里请参考**虚拟机登录 -> SSH 命令行登录**页面的[登录用户名](login/ssh.md#username)章节。
+    这里请参考**SSH 命令行登录**页面的[登录用户名](../login/ssh.md#username)章节。
 
 在断开与虚拟机的连接时输入 `exit` 即可。
 
-![ssh](images/vscode2vlab/SSH2.png)
+![ssh](../images/vscode2vlab/SSH2.png)
 
 ### 2. 使用公钥登录虚拟机
 
 使用公钥登录虚拟机可以免除每次输入密码的麻烦，我们首先要生成密钥对并下载到本地。
 
-这里下载密钥对的操作请参考**虚拟机登录 -> SSH 命令行登录**页面的[生成 SSH 密钥对并下载到本地](login/ssh.md#get-pubkey)章节。
+这里下载密钥对的操作请参考**SSH 命令行登录**页面的[生成 SSH 密钥对并下载到本地](../login/ssh.md#get-pubkey)章节。
 
 我们将私钥放在 `%UserProfile%\.ssh` 目录中，例如 `%UserProfile%\.ssh\vlab.pem`。
 
@@ -264,17 +266,17 @@ ssh [email protected]
 
 右键单击 `.pem` 文件，进入**属性 -> 安全 -> 高级**，可以看到以下界面。
 
-![permission](images/vscode2vlab/SSH3.png)
+![permission](../images/vscode2vlab/SSH3.png)
 
 然后将所有者改为个人用户（如果已经是则不用改），并且删除掉其他用户的权限（如果这里因为继承权限无法删除，则要先点击"禁用继承"）。如果在权限条目中没有个人用户，则需手动添加：在点击"添加"后点击"选择主体"，然后指定对象类型为"用户"，点击"高级"，开始立即查找，便可找到个人用户。将其权限设置为"完全控制"，确定添加即可。
 
-![adduser](images/vscode2vlab/SSH4.png)
+![adduser](../images/vscode2vlab/SSH4.png)
 
-![adduser](images/vscode2vlab/SSH5.png)
+![adduser](../images/vscode2vlab/SSH5.png)
 
 最后设置完毕如下：
 
-![permission finish](images/vscode2vlab/SSH6.png)
+![permission finish](../images/vscode2vlab/SSH6.png)
 
 修改权限后，可以在 CMD 或 PowerShell 中使用 ssh 命令登录：
 
@@ -304,38 +306,39 @@ Host vlab
 
 接下来我们在 VSCode 中通过 SSH 登录 Vlab。首先在 VSCode 中安装扩展 **Remote - SSH**。
 
-![VSCode Extension SSH](images/vscode2vlab/vs_vlab1.png)
+![VSCode Extension SSH](../images/vscode2vlab/vs_vlab1.png)
 
 安装后在左侧会出现**远程资源管理器**。如果前面已经按照教程配置好了 SSH，可以看到我们的虚拟机 Vlab。
 
 !!! info "注意"
-    若还未配置好 SSH 请按照上面的教程进行 SSH 配置，实现公钥登录并完成配置文件。
+
+    请先按照上面的教程进行 SSH 配置，实现公钥登录并完成配置文件。
 
 点击 **vlab** 右侧的图标，在现有的窗口/新窗口中连接 Vlab。在选择远程平台时选择 **Linux**。
 
-![connect](images/vscode2vlab/vs_vlab2.png)
+![connect](../images/vscode2vlab/vs_vlab2.png)
 
 首次连接时会显示“正在下载 VSCode 服务器”。这是正在 Vlab 虚拟机上安装 VSCode 服务器，时间可能比较长，请耐心等待。
 
-![wait](images/vscode2vlab/vs_vlab3.png)
+![wait](../images/vscode2vlab/vs_vlab3.png)
 
 下载好后，左下角显示 **SSH:vlab** 即连接成功。
 
-![connection success](images/vscode2vlab/vs_vlab4.png)
+![connection success](../images/vscode2vlab/vs_vlab4.png)
 
 在上方的**文件->打开文件夹**即可选择要打开的 Vlab 上的文件夹，新建文件同理。
 
-![open file](images/vscode2vlab/vs_vlab5.png)
+![open file](../images/vscode2vlab/vs_vlab5.png)
 
 我们也可以用快捷键 **Ctrl + \`** 打开终端，此时的终端环境是 Vlab 的，可以通过命令行对 Vlab 进行操作。
 
-![Terminal](images/vscode2vlab/vs_vlab6.png)
+![Terminal](../images/vscode2vlab/vs_vlab6.png)
 
 ## 本地 VSCode 编辑 Vlab 的 Verilog 项目 {#Vlab-verilog}
 
 截至目前，我们已经能用本地 VSCode 远程编辑 Vlab 上的文件了。但当我们用 VSCode 打开 Vlab 中新建的 `.v` 文件时，却发现没有了语法高亮。这是因为 Verilog-HDL/SystemVerilog 扩展被定义为在远程扩展主机中运行，故在此工作区中被禁用。我们需要在本地已安装的扩展中找到 Verilog-HDL/SystemVerilog，点击**在 SSH:vlab 中安装**，来启用该扩展。
 
-![Vlab Extention](images/vscode2vlab/vs_vlab7.png)
+![Vlab Extention](../images/vscode2vlab/vs_vlab7.png)
 
 然后我们的 Verilog 代码就有了语法高亮。但当我们编写代码时，会发现前面配置好的 ctags 和 iverilog 失效了：鼠标悬停不显示代码声明，“CTRL 鼠标点击跳转到代码声明”的功能失效，代码的语法错误也不会报错。
 
@@ -351,8 +354,8 @@ sudo apt install iverilog gtkwave universal-ctags
 
 然后在 VSCode 已打开的远程连接 Vlab 中打开 Verilog-HDL/SystemVerilog 的扩展设置，将**远程 [SSH:vlab]**和**工作区**中同[本地配置](#config-extension)（即“用户”一栏中的配置）进行设置。
 
-![Config Extention](images/vscode2vlab/vs_vlab8.png)
+![Config Extention](../images/vscode2vlab/vs_vlab8.png)
 
 完成后，我们就可以在本地 VSCode 对 Vlab 中的 Vivado 设计文件进行编辑了！
 
-![finish](images/vscode2vlab/vs_vlab9.png)
+![finish](../images/vscode2vlab/vs_vlab9.png)

mkdocs.yml

@@ -55,12 +55,12 @@ extra_css:
 markdown_extensions:
   - admonition
   - attr_list
-  - codehilite
   - footnotes
   - pymdownx.details
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight
   - pymdownx.mark
   - pymdownx.tabbed:
       alternate_style: true
@@ -73,7 +73,6 @@ markdown_extensions:
 nav:
   - 简介: index.md
   - 快速开始: quickstart.md
-  - 本地 VSCode 远程连接 Vlab: vscode2vlab.md
   - 虚拟机:
     - 虚拟机管理: web.md
     - 虚拟机登录:
@@ -87,6 +86,9 @@ nav:
   - 应用程序:
     - 在线 VSCode: apps/vscode.md
     - RISC-V 工具链: apps/riscv.md
+  - 教程:
+    - 本地 VSCode 远程连接 Vlab: tutorial/vscode2vlab.md
+    - Git 简明教程: tutorial/git.md
   - 其他:
     - 常见问题: faq.md
     - 通知公告: announcements.md
@@ -100,4 +102,3 @@ nav:
     - 资源下载: downloads.md
     - 致谢: credits.md
     - 招新: recruit.md
-    - Git 简明教程: tutorial/git.md