Skip to main content

在 GitHub Pages 上发布 DatomsDBS 技术文档

注意：这是内部技术文档，不应在公开文档站点中显示

本指南将帮助您在 GitHub Pages 上发布 DatomsDBS 技术文档。

🚀 快速设置​

步骤 1: 推送代码到 GitHub​

# 初始化 Git 仓库（如果还没有）
git init

# 添加所有文件
git add .

# 提交更改
git commit -m "Add GitHub Pages documentation setup"

# 添加远程仓库
git remote add origin https://github.com/YOUR_USERNAME/datomsDBS.git

# 推送到 GitHub
git push -u origin main

步骤 2: 启用 GitHub Pages​

  1. 进入仓库设置

    • 在 GitHub 上打开您的仓库
    • 点击 "Settings" 标签页

  2. 配置 Pages 设置

    • 在左侧菜单中找到 "Pages"
    • 在 "Source" 部分选择 "GitHub Actions"

  3. 等待部署完成

    • GitHub Actions 将自动构建和部署您的文档
    • 部署完成后，您将看到文档站点的 URL

步骤 3: 访问文档站点​

您的文档站点将可在以下地址访问：

https://YOUR_USERNAME.github.io/datomsDBS/

如果您使用的是组织账户或自定义域名，URL 可能会有所不同。

📁 项目结构​

为了支持 GitHub Pages，我们创建了以下文件结构：

datomsDBS/
├── _config.yml              # Jekyll 配置文件
├── Gemfile                  # Ruby 依赖管理
├── index.md                 # 主页面
├── .github/
│   └── workflows/
│       └── pages.yml        # GitHub Actions 工作流
└── docs/
    ├── datomsdbs_technical_documentation.md
    ├── api_reference.md
    ├── deployment_guide.md
    └── github-pages-setup.md

⚙️ 配置文件说明​

_config.yml​

Jekyll 配置文件，包含站点的基本设置：

title: DatomsDBS 技术文档
description: 现代化的数据资产管理平台 - 技术文档与API参考
baseurl: ""
url: ""
markdown: kramdown
highlighter: rouge
theme: minima

重要配置项：

  • baseurl: 如果您的仓库名不是根域名，需要设置为 "/repository-name"
  • url: 您的 GitHub Pages 域名
  • theme: 使用的 Jekyll 主题

Gemfile​

Ruby 依赖管理文件，定义了 Jekyll 和所需插件：

source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins
gem "minima", "~> 2.5"

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "jekyll-sitemap"
  gem "jekyll-seo-tag"
end

.github/workflows/pages.yml​

GitHub Actions 工作流，自动构建和部署文档：

name: Deploy GitHub Pages

on:
  push:
    branches: ["main", "master"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
          bundler-cache: true
      - uses: actions/configure-pages@v4
      - run: bundle exec jekyll build
      - uses: actions/upload-pages-artifact@v3

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/deploy-pages@v4

🎨 自定义主题​

使用默认主题​

我们使用 minima 主题，它是 GitHub Pages 的默认主题，提供：

  • 响应式设计
  • 语法高亮
  • 导航菜单
  • SEO 优化

自定义样式​

如果需要自定义样式，可以创建 assets/css/style.scss 文件：

@import "minima";

// 自定义样式
.site-header {
  background-color: #2c3e50;
}

.site-title {
  color: white !important;
}

// 代码块样式
.highlight {
  background: #f8f8f8;
  border-radius: 3px;
  padding: 1em;
}

📝 文档编写指南​

Front Matter​

每个文档页面都需要 YAML front matter：

---
layout: page
title: 页面标题
nav_order: 2
description: "页面描述"
permalink: /docs/page-url/
---

内部链接​

使用相对路径链接到其他文档：

[技术文档](docs/datomsdbs_technical_documentation.md)
[API 参考](docs/api_reference.md)
[部署指南](docs/deployment_guide.md)

代码高亮​

支持多种语言的语法高亮：

```bash
npm install
npm start
const express = require('express');
const app = express();
version: '3.8'
services:
  app:
    image: node:18

## 🔧 本地开发

### 安装依赖

```bash
# 安装 Ruby 和 Bundler
sudo apt-get install ruby-full build-essential zlib1g-dev
gem install jekyll bundler

# 安装项目依赖
bundle install

本地预览​

# 启动本地服务器
bundle exec jekyll serve

# 或启用实时重载
bundle exec jekyll serve --livereload

# 访问 http://localhost:4000

构建静态文件​

# 构建生产版本
bundle exec jekyll build

# 输出在 _site/ 目录

📊 高级功能​

搜索功能​

可以添加搜索插件：

# _config.yml
plugins:
  - jekyll-algolia

algolia:
  application_id: YOUR_APP_ID
  index_name: YOUR_INDEX_NAME
  search_only_api_key: YOUR_SEARCH_KEY

评论系统​

集成 Disqus 或 Utterances：

# _config.yml
disqus:
  shortname: your-disqus-shortname

# 或使用 Utterances (GitHub Issues)
utterances:
  repo: "your-username/your-repo"
  issue-term: "pathname"

分析统计​

添加 Google Analytics：

# _config.yml
google_analytics: UA-XXXXXXXX-X

🚨 常见问题​

部署失败​

问题: GitHub Actions 构建失败

解决方案:

  1. 检查 _config.yml 语法
  2. 确保所有 front matter 格式正确
  3. 查看 Actions 日志了解具体错误

样式显示异常​

问题: CSS 样式不生效

解决方案:

  1. 检查 baseurl 配置
  2. 确保 CSS 文件路径正确
  3. 清除浏览器缓存

链接无法访问​

问题: 内部链接返回 404

解决方案:

  1. 使用相对路径
  2. 检查文件路径和文件名
  3. 确保 permalink 设置正确

🔄 更新和维护​

自动更新​

每次推送到主分支时，GitHub Actions 会自动：

  1. 构建 Jekyll 站点
  2. 部署到 GitHub Pages
  3. 更新文档站点

手动触发​

可以在 GitHub Actions 页面手动触发部署：

  1. 进入 "Actions" 标签页
  2. 选择 "Deploy GitHub Pages" 工作流
  3. 点击 "Run workflow"

版本管理​

建议使用 Git 标签管理文档版本：

# 创建版本标签
git tag -a v1.0.0 -m "Documentation v1.0.0"
git push origin v1.0.0

完成设置后，您的 DatomsDBS 技术文档将在 GitHub Pages 上实时更新，为用户提供最新的技术资料！ 🎉