init

Signed-off-by: Ashing Zheng <axingfly@gmail.com>

Author: ronething

.gitignore

@@ -0,0 +1,33 @@
+.idea/
+.vscode/
+WORKSPACE
+.DS_Store
+# don't check in the build output of the book
+book/book
+
+# ignore auto-generated dir by `mdbook serve`
+src/docs
+
+# Editor temp files
+*~
+\#*#
+*.swp
+
+# Skip bazel dirs
+/bazel-*
+
+# skip bin dirs
+**/bin
+**/testbin
+
+# skip .out files (coverage tests)
+*.out
+
+# skip testdata go.sum, since it may have
+# different result depending on go version
+/testdata/**/go.sum
+book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/bin
+/testdata/**legacy**
+
+## Skip testdata files that generate by tests using TestContext
+**/e2e-*/**

CONTRIBUTING-ROLES.md

@@ -0,0 +1,152 @@
+Contributing Roles
+==================
+
+## Direct Code-Related Roles
+
+While anyone (who's signed the [CLA and follows the code of
+conduct](../CONTRIBUTING.md)) is welcome to contribute to the Kubebuilder
+project, we've got two "formal" roles that carry additional privileges and
+responsibilities: *reviewer* and *approver*.
+
+In a nutshell, reviewers and approvers are officially recognized to make
+day-to-day and overarching technical decisions within parts of the
+project, or the project as a whole.  We follow a similar set of
+definitions to the [main Kubernetes project itself][kube-ladder], with
+slightly looser requirements.
+
+As much as possible, we want people to help take on responsibility for the
+project -- these guidelines are attempts to make it *easier* for this to
+happen, *not harder*.  If you've got any questions, just reach out on
+Slack to one of the [subproject leads][kb-leads] (called
+kubebuilder-admins in the `OWNERS_ALIASES` file).
+
+## Prerequisite: Member
+
+Anyone who wants to become a reviewer or approver must first be a [member
+of the Kubernetes project][kube-member].  The aforementioned doc has more
+details, but the gist is that you must have made a couple of contributions to
+some part of the Kubernetes project -- *this includes Kubebuilder and
+related repos*.  Then, you need two existing members to sponsor you.
+
+**If you've contributed a few times to Kubebuilder, we'll be happy to
+sponsor you, just ping us on Slack :-)**
+
+## Reviewers
+
+Reviewers are recognized as able to provide code reviews for parts of the
+codebase and are entered into the `reviewers` section of one or more
+`OWNERS` files.  You'll get auto-assigned reviews for your area of the
+codebase and are generally expected to review for correctness,
+testing, general code organization, etc.  Reviewers may review for design
+as well, but approvers have the final say on that.
+
+Things to look for:
+
+- does this code work, and is it written performantly and idiomatically?
+- is it tested?
+- is it organized nicely?  Is it maintainable?
+- is it documented?
+- does it need to be threadsafe?  Is it?
+- Take a glance at the stuff for approvers, if you can.
+
+Reviewers' `/lgtm` marks are generally trusted by approvers to means that
+the code is ready for one last look-over before merging.
+
+### Becoming a Reviewer
+
+The criteria for becoming a reviewer are:
+
+- Give 5-10 reviews on PRs
+- Contribute or review 3-5 PRs substantially (i.e. take on the role of the
+  defacto "main" reviewer for the PR, contribute a bugfix or feature, etc)
+
+Usually, this will need to occur within a single repository, but if you've
+worked on a cross-cutting feature, it's ok to count PRs across
+repositories.
+
+Once you meet those criteria, submit yourself as a reviewer in the
+`OWNERS` file or files that you feel represent your areas of knowledge via
+a PR to the relevant repository.
+
+## Approvers
+
+Approvers provide the final say as to whether a piece of code is merged.
+Once approvals (`/approve`) are given for each piece of the affected code
+(and a reviewer or approver has added `/lgtm`), the code will merge.
+
+Approvers are responsible for giving the code a final once-over before
+merge, and do an overall design/API review.
+
+Things to look for:
+
+- Does the API exposed to the user make sense, and is it easy to use?
+- Is it backward compatible?
+- Will it accommodate new changes in the future?
+- Is it extensible/layer-able (see [DESIGN.md](../DESIGN.md))?
+- Does it expose a new type from `k8s.io/XYZ`, and, if so, is it worth it?
+  Is that piece well-designed?
+
+**For large changes, approvers are responsible for getting reasonable
+consensus**.  With the power to approve such changes comes the
+responsibility of ensuring that the project as a whole has time to discuss
+them.
+
+### Becoming an Approver
+
+All approvers need to start as reviewers.  The criteria for becoming
+an approver is:
+
+- Be a reviewer in the area for a couple of months
+- Be the "main" reviewer or contributor for 5-10 substantial (bugfixes,
+  features, etc) PRs where approvers did not need to leave substantial
+  additional comments (i.e. where you were acting as a defacto approver).
+
+Once you've met those criteria, you can submit yourself as an approver
+using a PR that edits the relevant `OWNERS` files appropriately.  The
+existing approvers will then approve the change with lazy consensus.  If
+you feel more comfortable asking before submitting the PR, feel free to
+ping one of the [subproject leads][kb-leads] (called kubebuilder-admins in
+the `OWNERS_ALIASES` file) on Slack.
+
+## Indirectly Code-Related/Non-Code Roles
+
+We're always looking for help with other areas of the project as well, such
+as:
+
+### Docs
+
+Docs contributors are always welcome.  Docs folks can also become
+reviewers/approvers for the book by following the same process above.
+
+### Triage
+
+Help to triage our issues is also welcome.  Folks doing triage are
+responsible for using the following commands to mark PRs and issues with
+one or more labels, and should also feel free to help answer questions:
+
+- `/kind {bug|feature|documentation}`: things that are broken/new
+  things/things with lots of words, respectively
+
+- `/triage support`: questions, and things that might be bugs but might
+  just be confused about how to use something
+
+- `/priority {backlog|important-longterm|important-soon|critical-urgent}`:
+  how soon we need to deal with the thing (if someone wants
+  to/eventually/pretty soon/RIGHT NOW OMG THINGS ARE ON FIRE,
+  respectively)
+
+- `/good-first-issue`: this is pretty straightforward to implement, has
+  a clear plan, and clear criteria for being complete
+
+- `/help`: this could feasibly still be picked up by someone new-ish, but
+  has some wrinkles or nitty-gritty details that might not make it a good
+  first issue
+
+See the [Prow reference](https://prow.k8s.io/command-help) for more
+details.
+
+[kube-ladder]: https://github.com/kubernetes/community/blob/master/community-membership.md "Kubernetes Community Membership"
+
+[kube-member]: https://github.com/kubernetes/community/blob/master/community-membership.md#member "Kubernetes Project Member"
+
+[kb-leads]: ../OWNERS_ALIASES "Root OWNERS file -- kubebuilder-admins"

README.md

@@ -0,0 +1,18 @@
+# Running mdBook
+
+The kubebuilder book is served using [mdBook](https://github.com/rust-lang-nursery/mdBook). If you want to test changes to the book locally, follow these directions:
+
+1. Follow the instructions at [https://rust-lang.github.io/mdBook/guide/installation.html](https://rust-lang.github.io/mdBook/guide/installation.html) to
+   install mdBook.
+2. Make sure [controller-gen](https://pkg.go.dev/sigs.k8s.io/controller-tools/cmd/controller-gen) is installed in `$GOPATH`.
+3. cd into the `docs/book` directory
+4. Run `mdbook serve`
+5. Visit [http://localhost:3000](http://localhost:3000)
+
+# Steps to deploy
+
+There are no manual steps needed to deploy the website.
+
+Kubebuilder book website is deployed on Netlify.
+There is a preview of the website for each PR.
+As soon as the PR is merged, the website will be built and deployed on Netlify.

book/.firebaserc

@@ -0,0 +1 @@
+{}

book/book.md

@@ -0,0 +1,72 @@
+# Kubebuilder 文档站部署说明
+
+本文说明如何在本地构建 `docs/book` 文档站，并将其部署到独立站点。命令与脚本保持仓库现状，不额外引入新依赖。
+
+## 1. 环境准备
+
+- 安装 Go ≥ 1.23（建议与仓库中 `GO_VERSION=1.23.0` 保持一致）。
+- 确保 `curl`、`tar`、`unzip` 可用，脚本会下载 mdBook 与 `controller-gen`。
+- 若在 CI 或容器中运行，可使用 `gimme` 预装 Go 版本，以兼容 `install-and-build.sh` 的逻辑。
+
+## 2. 本地构建
+
+所有命令均需在仓库根目录执行：
+
+```bash
+GO_VERSION=1.23.0 ./docs/book/install-and-build.sh
+```
+
+脚本会：
+
+- 根据当前平台下载 mdBook 0.4.40 至临时目录。
+- 安装 `sigs.k8s.io/controller-tools/cmd/controller-gen@v0.19.0` 到 `docs/book/functions`。
+- 运行自定义预处理器 `litgo.sh` 与 `markerdocs.sh`。
+- 输出静态站点到 `docs/book/book`。
+
+## 3. 本地预览
+
+构建成功后，可使用任意静态文件服务器本地预览，例如：
+
+```bash
+npx serve docs/book/book
+```
+
+或使用 Netlify CLI 复现线上行为：
+
+```bash
+netlify dev --dir docs/book/book
+```
+
+## 4. 独立部署流程
+
+### 4.1 直接同步静态文件
+
+1. 执行构建脚本得到 `docs/book/book` 内容。
+2. 同步该目录下的静态文件至目标托管（如 GitHub Pages、S3、Cloudflare Pages、Vercel）。
+3. 若平台支持自定义 Header/Redirect，可将 `docs/book/functions` 中的逻辑迁移到对应的 Edge Function 或重写规则，以保留下载链接重定向能力。
+
+### 4.2 Netlify 单独站点
+
+若想在新域名上继续使用 Netlify：
+
+1. 新建 Netlify 站点，仓库指向本项目但使用独立分支或 `docs/book` 子目录。
+2. 在站点设置中配置：
+   - **Base directory**: `docs/book`
+   - **Build command**: `GO_VERSION=1.23.0 ./install-and-build.sh`
+   - **Publish directory**: `docs/book/book`
+   - **Functions directory**: `docs/book/functions`
+3. 绑定新域名，配置 HTTPS 即可上线。
+
+## 5. CI/CD 建议
+
+- 在新站点仓库或分支上添加构建流程（如 GitHub Actions），执行同一脚本并发布工件。
+- 若构建频次高，建议封装一个包含 Go 与 mdBook 的轻量容器镜像，缩短脚本下载时间。
+- 可以引入链接检查、Markdown lint 或 `mdbook build --dest-dir` 的 dry run 以提前发现断链或预处理器错误。
+
+## 6. 常见问题排查
+
+- **mdBook 下载失败**：检查是否被代理阻断，可预先下载并缓存到镜像或内部文件仓库。
+- **预处理脚本报错**：确认 `litgo.sh` 与 `markerdocs.sh` 拥有执行权限，并在 Bash 环境下运行。
+- **Go 依赖缺失**：确保 `GOBIN` 写入路径在 `PATH` 中，或手动导出 `export PATH=$(go env GOBIN):$PATH`。
+
+完成上述步骤后，你即可在本地验证文档站，并将同样的构建产物部署到新的独立网站。

book/book.toml

@@ -0,0 +1,24 @@
+[book]
+authors = ["The Kubebuilder Maintainers"]
+multilingual = false
+src = "src"
+title = "The Kubebuilder Book"
+
+[output.html]
+smart-punctuation = true
+additional-css = ["theme/css/markers.css", "theme/css/custom.css", "theme/css/version-dropdown.css"]
+git-repository-url = "https://github.com/kubernetes-sigs/kubebuilder"
+edit-url-template = "https://github.com/kubernetes-sigs/kubebuilder/edit/master/docs/book/{path}"
+
+[preprocessor.literatego]
+command = "./litgo.sh"
+
+[preprocessor.markerdocs]
+command = "./markerdocs.sh"
+
+[context.environment]
+  environment = { GO_VERSION = "1.23" }
+
+[context.deploy-preview.environment]
+  environment = { GO_VERSION = "1.23" }
+

book/functions/handle-version.js

@@ -0,0 +1,37 @@
+function notFound(info) {
+    return {
+        statusCode: 404,
+        headers: {'content-type': 'text/html'},
+        body: ("<h1>Not Found</h1>"+
+            "<p>You shouldn't see this page, please file a bug</p>"+
+            `<details><summary>debug details</summary><pre><code>${JSON.stringify(info)}</code></pre></details>`
+        ),
+    };
+}
+
+function redirectToDownload(version, file) {
+    const loc = `https://github.com/kubernetes-sigs/kubebuilder/releases/download/v${version}/${file}`;
+    return {
+        statusCode: 302,
+        headers: {'location': loc, 'content-type': 'text/plain'},
+        body: `Redirecting to ${loc}`,
+    };
+}
+
+
+exports.handler = async function(evt, ctx) {
+    // grab the prefix too to check for coherence
+    const [prefix, version, os, arch] = evt.path.split("/").slice(-4);
+    if (prefix !== 'releases' || !version || !os || !arch) {
+        return notFound({version: version, os: os, arch: arch, prefix: prefix, rawPath: evt.path});
+    }
+
+    switch(version[0]) {
+        case '1':
+            // fallthrough
+        case '2':
+            return redirectToDownload(version, `kubebuilder_${version}_${os}_${arch}.tar.gz`);
+        default:
+            return redirectToDownload(version, `kubebuilder_${os}_${arch}`);
+    }
+}