zaproxy/zaproxy-website
GitHub: zaproxy/zaproxy-website
ZAP 官方网站的源码仓库，基于 Hugo 构建的静态文档站点项目。
Stars: 78 | Forks: 124
# ZAP 网站
## 开发
要在网站上工作，你需要安装 node.js 或 Docker。在你的开发环境中，`npm run preview` 将在端口 3000 上启动一个 webpack-dev-server，用于开发，当检测到文件更改时，它会热重载网站。
### Docker
推荐的开发设置是使用 Docker。
```
# 构建镜像
docker build -t zaproxy-website .
# 使用 zaproxy-website 镜像启动容器
docker run -it -v "$(pwd)/site:/app/site" \
-v "$(pwd)/src:/app/src" -p 3000:3000 zaproxy-website npm run preview
```
### 依赖
在开发方面，该网站严重依赖 node.js 来构建前端 CSS 和 JavaScript 的实用程序。修改网站 JavaScript 的入口点是 `src/index.js`，它使用 babel 进行转译，并使用 webpack 包进行打包。
```
# 检查相关漏洞
npm audit
# 检查包
npm outdated
# 更新包
npm update @babel/core
```
### 构建
```
./bin/build.sh
cp -r ./dist/ ../zaproxy-website-builds
cd ../zaproxy-website-builds
git push origin staging
```
## Hugo
*一般而言，术语 post（文章）和 page（页面）可以互换使用，例外情况是在定义内容类型时（`type: post`）*
### 结构
https://gohugo.io/getting-started/directory-structure/
```
|--site // Everything in here will be built with hugo
| |--content // Posts and collections - ask if you need extra posts
| |--data // YAML data files with any data for use in examples
| |--layouts // This is where all templates go
| | |--_default // This is where the default layouts live
| | |--partials // This is where includes live
| | |--index.html // The index page
| |--static // Files in here ends up in the public folder
|--src // Files that will pass through the asset pipeline
| |--css // Webpack will bundle imported css separately
| |--index.js // index.js is the webpack entry for your css & js assets
```
#### 内容
要添加或修改内容，请转到 `site/content/`。
内容以 markdown 文件的形式编写，带有 YAML 头信息，其中包括有关文章的详细信息，如标题、日期和布局。文件名在生成网站时会被转换为 URL。名为 `site/content/download.md` 的文件变为 `/download`。
此外，你在该目录中创建的任何文件夹结构都将反映在网站的 URL 层次结构中。这意味着 `site/content/blog/2017-08-22-zap-browser-launch.md` 变为 `/blog/2017-08-22-zap-browser-launch`。
**示例**
```
---
type: page
title: Get Involved
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus et dui ligula.
Donec semper ex at molestie scelerisque. In sodales bibendum leo, vitae porttitor
est viverra at. Phasellus tincidunt enim ac rutrum convallis. Duis at tellus a
erat consequat fringilla. Ut augue leo, blandit vel d
## Mauris
```
你也可以使用 `hugo` 命令来创建 yaml 内容文件。
```
# 进入站点目录
cd site/
# 创建通用内容文件
hugo new contributing.md
# 使用 site/archetypes/blog.md 模板创建内容文件
hugo new blog/$(date -v +7d '+%Y-%m-%d')-learning-zap-api/index.md
```
为了保持内容井井有条，你还可以选择将文章的内容封装在一个目录中。如果一篇文章包含大量图片或其他相关资产，将这些资产与文章放在一起会比将它们全部放在资产目录中更整洁。
例如，你可以使用 `site/content/download/index.md` 来代替 `site/content/download.md`，并且所有文章相关的图片也将位于同一个 `download` 目录中。
##### 新内容
要添加新的内容类别（如 addons 或 wiki 条目），请按照下面的模式，以 addons 为例
- 创建内容目录 `mkdir -p site/content/addons/{images,icons}`
- 如果该部分中没有大量媒体，请将图片复制到 images 目录中
- 如果内容包含大量媒体，请勿为每篇文章创建单个 markdown 文件，而是创建一个以文章名称命名的目录
- `site/content/addons/active-scan-rules/images/`
- 如果存在子页面内容，则还需要创建反映内容结构的目录
- 例如，对于 Access Control Context Options，你可以根据内容深度使用以下结构之一
- `site/content/addons/access-control/context-options/_index.md`
- `site/content/addons/access-control/context-options.md`
- 当你创建条目时，在头部包含一个 type
###### 示例
`site/content/addons/active-scan-rules.md`
```
---
title: "Active Scan Rules"
type: addon
status: alpha
icon:
---
```
##### 高亮重要内容
下面的示例使用与 Github Markdown 相同的语法。负责渲染它们的模板位于 `site/layouts/_default/_markup/render-blockquote.html`
展示所有这些示例的测试页面可在 https://www.zaproxy.org/docs/md-callout-examples/ 访问
```
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes.
```
#### 布局
要控制渲染什么 HTML，你需要使用网站模板。在 `site/layouts/` 目录中，你会发现许多带有各种模板标签的 HTML 文件。首先要查看的文件是 `site/layouts/_default/baseof.html` —— 这是 Hugo 用来构建你的网站的基础布局，其他模板会扩展它。Hugo 有一个查找顺序，用于将内容条目关联到模板。对于一个类型为 post（`type: post`）的单一条目，Hugo 会在 `site/layouts/post/single.html` 中查找布局，如果该布局不存在，它将回退到 `site/layouts/_default/single.html`。
对于普通文章，查找解析效果很好，但有时你会遇到需要自定义布局的文章，例如下载页面。在这些情况下，你可以在内容 markdown 文件中指定布局，它会查找相应的模板。
这就是 `site/content/download.md` 目前的样子，它解析为 `site/layouts/page/download.html` 中的模板。
```
type: page
layout: download
---
```
- https://gohugo.io/templates/introduction/
- https://gohugo.io/templates/lookup-order/
#### 数据
在网站中共享的数据位于 `site/data/`。例如，所有网站作者的列表就是你会希望在网站的多个位置引用的一段数据。你可以创建 `site/data/authors.yaml`。
```
---
- name: 'Simon Bennetts'
picture: 'https://pbs.twimg.com/profile_images/2186782633/simonbennetts2_400x400.jpg'
twitter: '@psiinon'
is_core: true
- name: 'David Scrobonia'
picture: 'https://pbs.twimg.com/profile_images/1132029219876347904/FYA3rHRq_400x400.png'
twitter: '@david_scrobonia'
is_core: true
```
随后，在模板中，你可以引用该数据，模板将进行渲染。
```
{{ range $author := $.Site.Data.authors }}
{{ end }}
```
https://gohugo.io/templates/data-templates/
#### 前端资产
##### 静态
对于那些完全静态且不需要经过资产管道的资产，
请使用 `site/static` 文件夹。图片、字体文件等都放在那里。静态文件夹中的文件最终会位于 Web 根目录中。所以一个名为 `site/static/favicon.ico` 的文件
最终将作为 `/favicon.ico` 可用，依此类推...
##### CSS/SCSS
所有的 CSS 都是用 SCSS ("Sassy CSS") 编写的，所有文件位于 `src/css/`，其中 `src/css/main.scss` 是入口点，定义了主变量并导入所需的样式。
样式按广泛的类别、组件和文章特定样式进行分隔。例如，如果你需要更改整个网站的排版，`src/css/_type.scss` 是要编辑的文件。
https://sass-lang.com/documentation/syntax
##### JavaScript
`src/index.js` 文件是 webpack 的入口点，将被构建为 `/dist/main.js`
你可以使用 **ES6**，并使用相对导入或从 npm 导入库。任何导入到 `index.js` 的 CSS 文件都将通过 Webpack 处理，使用 [PostCSS Next](http://cssnext.io/) 编译，并压缩到 `/dist/[name].[hash:5].css`。导入语句将作为构建的一部分进行解析。
- https://babeljs.io/
- https://webpack.js.org/
### 基本概念
你可以在他们的文档中阅读更多关于 Hugo 模板语言的信息。
那里最有用的页面是关于可用函数的页面。
- https://gohugo.io/templates/overview/
- https://gohugo.io/templates/functions/
### 环境变量
为了区分开发和生产（即构建）阶段，所有的 gulp 任务都运行在一个名为 `development` 或 `production` 的 node 环境变量下。
你可以在主题文件中使用 `getenv "NODE_ENV"` 访问环境变量。请参阅以下示例中的条件语句：
```
{{ if eq (getenv "NODE_ENV") "development" }}You're in development!{{ end }}
```
所有以 _build_ 开头的任务都会将环境变量设置为 `production` —— 其他任务将其设置为 `development`。
### 有用的链接
- https://regisphilibert.com/blog/2018/01/hugo-page-resources-and-how-to-use-them/
- https://regisphilibert.com/blog/2018/02/hugo-the-scope-the-context-and-the-dot/
- https://gist.github.com/sebz/efddfc8fdcb6b480f567
- https://en.jeffprod.com/blog/2018/build-your-own-hugo-website-search-engine/
- https://github.com/vjeantet/hugo-theme-docdock
- https://harmstyler.me/posts/2019/how-to-pass-variables-to-a-partial-template-in-hugo/
标签：Babel, CMS安全, CSS, DNS枚举, Docker, GNU通用公共许可证, Hugo, JavaScript, MITM代理, NIDS, Node.js, npm, OWASP ZAP, Syscall, Webpack, Web开发, 前端工程化, 后端开发, 响应拦截, 安全扫描, 安全防御评估, 容器化, 技术文档, 时序注入, 暗色界面, 网站源码, 网络安全工具, 请求拦截, 静态网站生成器, 项目文档