GitLab Pages 安装与使用指南

GitLab Pages 安装与使用指南

GitLab-Pages:eyes: GitHub Pages, for GitLab. 项目地址:https://gitcode.com/gh_mirrors/gi/GitLab-Pages

1. 项目的目录结构及介绍

尽管提供的链接并不是一个具体GitLab Pages项目的GitHub仓库示例,但是通常一个准备用于GitLab Pages服务的项目目录结构可能如下:

├── .gitlab-ci.yml          # GitLab CI/CD 配置文件 
├── assets                   # 存放静态资源如图片或样式等  
│   ├── css                  # CSS 样式表存放位置  
│   └── img                  # 图片资源存放位置   
└── src                      # 主要源码存放位置
    └── index.html           # 网站主页HTML文件

• .gitlab-ci.yml: GitLab CI/CD pipeline 的配置文件，定义了项目构建、测试和发布自动化流程。

• assets: 全局静态资源文件存放目录，一般包括CSS、JS库和图像等资源。

  • css: 所有的CSS样式表文件存放在该目录下。
  • img: 所有的图片资源文件存放在该目录下。

• src: 工程主文件目录，存放网站的主要源码。

  • index.html: 网站入口HTML文件。

请注意，为了适配GitLab Pages的服务特性，项目应确保在构建完成后能够将所有静态内容放置于名为public的目录下，即使这个目录在项目目录中并不一定直接存在（因为GitLab Pages会寻找项目repository根目录下的public目录）。

2. 项目的启动文件介绍

对于GitLab Pages而言，“启动”更多指的是通过GitLab CI/CD pipeline自动生成并部署静态站点的过程。这里的关键“启动文件”便是.gitlab-ci.yml。

.gitlab-ci.yml

此YAML文件被GitLab Runner读取执行，其中包含了多个job，如：

• pages: 将编译后的HTML/CSS/JS等文件复制到public目录，以供GitLab Pages抓取和展示；
• deploy-pages: 推送public目录的内容至GitLab repo的gh-pages分支或其他指定分支；

典型的一个示例配置可以像这样：

image: node:latest

cache:
  paths:
    - node_modules/

variables:
  GIT_STRATEGY: clone

stages:
  - test
  - deploy

test_job:
  stage: test
  script:
    - npm ci
    - npm run lint
    - npm test

pages:
  image: ruby:latest
  script:
    - gem install jekyll bundler
    - bundle exec jekyll build --source=docs --destination=public
  artifacts:
    paths:
      - public/
  only:
    - master

deploy-pages:
  stage: deploy
  dependencies:
    - pages
  script:
    - rm -rf public/.git
    - cd public
    - git init
    - git config user.name "Your Name"
    - git config user.email "your@email.com"
    - git add .
    - git commit -m "Update pages"
    - git push origin gh-pages

以上示例中，pages job使用Jekyll工具将位于docs目录内的Markdown文件转换为静态网页，并放置于public目录中，然后由deploy-pages job负责推送这些静态文件至gh-pages分支以便GitLab Pages显示。

3. 项目的配置文件介绍

在GitLab Pages相关的项目中，核心配置主要存在于.gitlab-ci.yml文件里。至于其他可存在的配置文件，例如在使用Jekyll作为静态站点生成器时，可能会见到_config.yml这样的文件来定制站点属性。

_config.yml （当使用 Jekyll）

Jekyll 使用 _config.yml 文件进行全局配置，涵盖诸如站点名称、描述、作者信息以及布局、导航菜单等方面的设定。以下是一个简化的配置文件实例：

title: Glavin的博客
author: Glavin001
description: A blog about programming and life.
baseurl: "/blog"        # GitHub 和 GitLab Pages 上都会用到的基础URL前缀
google_analytics: UA-XXXX-Y   # 添加Google分析跟踪ID

通过上述配置文件对站点的基本元数据进行定义后，在Jekyll渲染网站时便会依据这些设定值填充内容。特别值得注意的是，baseurl 参数需恰当地配置，它影响着网站链接的相对路径构造。

---

这些基本配置和构建步骤构成了GitLab Pages项目的核心操作框架，使得开发者能够高效地设计、开发并上线自己的个人或项目相关静态网页。

GitLab-Pages:eyes: GitHub Pages, for GitLab. 项目地址:https://gitcode.com/gh_mirrors/gi/GitLab-Pages