hashicorp/vault-website

Vault Website

镜像概述和主要用途

本Docker镜像用于在本地运行Vault文档网站，该网站基于NextJS项目构建静态站点。通过Docker可快速搭建本地开发环境，适合需要预览Vault文档网站或进行文档贡献的用户使用。

贡献欢迎

若发现拼写错误或希望改进HTML、CSS、JavaScript，欢迎进行贡献。可像常规GitHub项目一样提交issue或拉取请求，我们将合并贡献🚀

本地运行网站

网站可通过Node.js或Docker在本地运行。选择Docker方式时，由于额外开销，速度会稍慢，因此频繁贡献者建议使用Node.js。此外，vim用户需注意，swapfile使用可能影响实时重载功能，需在vim中执行:set backupcopy=yes以避免问题。

使用Docker

本地运行简单便捷。确保已安装Docker，克隆仓库后运行make，然后访问http://localhost:3000。

Docker镜像预安装了所有网站依赖，因此启动快速简单，但如需修改依赖并在Docker中测试，需构建新镜像。此时可运行make build-image生成含更新依赖的本地Docker镜像，再运行make website-local使用该镜像预览。

使用Node.js

若本地开发环境安装了支持版本（v10.0.0+）的https://nodejs.org/en/，可执行：

bash
npm install
npm start

然后访问http://localhost:3000。从GitHub拉取新代码后，需重新运行npm install；否则无需每次运行时重新执行，直接npm start即可启动。

编辑内容

Markdown文件

文档内容采用https://www.markdownguide.org/cheat-sheet/编写，所有文件位于`/pages`目录下。

创建新Markdown页面时，在pages/目录下创建以.mdx结尾的文件，路径将对应URL路由。例如，pages/hello/world.mdx将通过/hello/world URL访问。

文件支持YAML frontmatter，为可选配置，所有键均有默认值：

yaml
---
title: '我的标题'
description: "页面内容的详细且简洁描述"
---

YAML frontmatter关键键值：

• title (字符串) - 设置HTML标题
• description (字符串) - 设置HTML描述

⚠️由于api是NextJS的保留目录，所有/api/**页面均位于/pages/api-docs路径下。

侧边栏编辑

侧边栏结构由/data目录下的文件控制：

• 编辑此文件更改文档侧边栏
• 编辑此文件更改API文档侧边栏

嵌套侧边栏项需添加category键值（对应pages目录下的目录名）和content键值（对应目录下的文件名）。

创建新页面

当前创建新页面存在小问题：若在服务器运行时通过子导航数据链接新页面，会提示页面未找到，重启服务器即可解决。

部署

网站托管于Netlify，配置为推送代码至stable-website分支时自动部署。提交更改website文件夹的拉取请求时，GitHub检查中会显示部署预览，可用于验证文档更改的实际效果。stable-website分支的部署与预览部署效果一致。