基于 Jekyll 的 Quarkus.io 网站

快速入门

这些说明将帮助你在本地机器上获取 Quarkus.io 网站的副本，用于开发和测试目的。

安装

使用 Docker 或 Podman

1. Install Docker Desktop or Podman Desktop

2. Fork the project repository, then clone your fork:

   git clone git@github.com:YOUR_USER_NAME/quarkusio.github.io.git

3. Change into the project directory:

   cd quarkusio.github.io

4. Run Docker Compose or Podman Compose:

   docker compose up

   or

   podman compose up

默认情况下，这不包含指南。若要包含指南，请使用：

docker compose --file docker-compose_with_guides.yml up

如果指南构建在完成前突然终止，请确保您的 容器引擎已分配足够的内存（至少需要 5GB）。

[!NOTE] 启动过程可能需要几分钟，具体取决于您的系统。在此期间，您可能会看到包含警告或配置信息的日志（例如，AutoPages 和 asciidoctor 警告）。这是 Jekyll 构建站点时的正常行为。服务器运行后，您会看到如下输出：

jekyll-1  |   Server address: http://0.0.0.0:4000/
jekyll-1  |   Server running... press ctrl-c to stop.

如果发生提及名称冲突的错误，请尝试：

docker compose up --force-recreate

5. 现在浏览到 http://localhost:4000.

使用本地 Ruby 环境

Jekyll 静态站点生成器文档.

1. Install a full Ruby development environment. If you use rvm, run: rvm use 3.2.3.

2. Install bundler gems

   gem install bundler

3. Fork the project repository, then clone your fork.

   git clone git@github.com:YOUR_USER_NAME/quarkusio.github.io.git

4. Change into the project directory:

   cd quarkusio.github.io

5. Use bundler to fetch all required gems in their respective versions

   bundle install

6. Build the site and make it available on a local server

   ./serve.sh

   Or if you want it faster and okay to not have guides included use the following:

   ./serve-noguides.sh

7. 现在浏览到 http://localhost:4000

[!NOTE] 如果在上述过程中遇到任何意外错误，请参阅 故障排除 页面或 需求 页面，您可能缺少开发头文件或其他先决条件。

有关 Jekyll 用法的更多信息，请参阅 Jekyll 分步教程。

部署到 GitHub Pages

网站部署由 GitHub Actions 自动执行（当提交推送到 main 分支时）。 如果由于某种原因您需要从本地机器部署，请遵循以下说明：

1. 安装 act 可执行文件以在本地运行 GitHub Actions
2. 运行 act -s GITHUB_TOKEN=<GITHUB_TOKEN>，其中 <GITHUB_TOKEN> 需要替换为一个允许您推送到 https://github.com/quarkusio/quarkusio.github.io 仓库的令牌。

撰写博客

[!WARNING] 使用生成式 AI 辅助 写作是可以的，但请不要用它来撰写整篇文章。 如果使用不当，生成式 AI 倾向于使用复杂的词汇和短语。这使得内容难以阅读和理解。始终从人类读者的角度审查您的博客，确保其事实正确，并特别保留内容中的人文气息和观点。

要撰写一篇博客：

• 在 _data/authors.yaml 中创建一个作者条目

  • emailhash 您可以通过在 Linux 上运行 echo -n your@email.org | md5sum 或在 macOS 上运行 echo -n your@email.org | md5 来获取，使用您从 Gravatar 服务 注册的电子邮件地址，

• 在 _posts 下创建一个博客条目

  • 文件名为 yyyy-mm-dd-slug.adoc 将日期设置为与 asciidoc 前言中相同的值。

• 使用 tags 时应谨慎，因为会为它们创建归档页面。以下是应尝试遵循的一些基本规则：

  • quarkus-release 用于 Quarkus 发布博客
  • announcement 用于具有一定影响的一般公告。
  • extension 用于与特定扩展相关的博客。
  • user-story 用于采用 Quarkus 的用户/公司的故事。
  • development-tips 用于包含使用 Quarkus 或 Quarkus 本身进行开发的技巧的博客。
  • 如果文章对某项技术有重大提及/相关性，请添加特定技术标签，如 kafka。
  • 标签是空格分隔的列表 tags:extension grpc
  • 标签必须为小写

• 它是 asciidoc 格式，示例如 2019-06-05-quarkus-and-web-ui-development-mode.adoc 所示

  • 请注意，asciidoc 前言中的 date 属性定义了文章的发布时间。在本地测试时，请添加 --future 标志，以确保文章包含在生成的站点中。

• 向 main 分支发送拉取请求，然后大功告成

翻译/本地化 (l10n)

主站点 (quarkus.io) 使用英文编写。

quarkus.io 的社区驱动本地化版本有独立的仓库：

• ja.quarkus.io 用于日语
• cn.quarkus.io 用于简体中文
• es.quarkus.io 用于西班牙语
• pt.quarkus.io 用于巴西葡萄牙语

如果您想为这些工作做出贡献，请阅读这些项目中的 README。如果您希望 启动另一个翻译，请在此主仓库中提交一个 issue。

为 l10n 站点启用 DNS

一旦本地化站点的内容翻译达到足够比例，就需要启用 DNS。为此，请让其中一位 Red Hat 管理员提交 一张工单给 IT，请求 XX 域名：

We need a CNAME record set up for XX.quarkus.io to have it serve out GitHub pages. 

The CNAME record for XX.quarkus.io should point to "quarkusio.github.io.".

有关更多信息，请参阅 https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site 中的第 5 步。

贡献

请阅读 CONTRIBUTING.md 以了解我们的行为准则以及向我们提交 pull request 的流程。

[!IMPORTANT] 指南维护在 Quarkus 主仓库中，pull request 应提交至该仓库：https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc。

许可证

本网站采用 Creative Commons Attribution 3.0 许可证。