开源项目「Contrast」安装与使用指南

开源项目「Contrast」安装与使用指南

contrast Jekyll Theme 项目地址: https://gitcode.com/gh_mirrors/co/contrast

项目概述

「Contrast」是一款由 Niklas Buschmann 开发的基于 Jekyll 的主题，适用于构建简洁美观的个人博客。它支持暗黑模式、可选侧边栏、MathJax 支持，以及无需依赖外部资源的特性。此外，该主题还提供归档页面、分页、响应式设计、语法高亮，并且可以集成 Disqus 或 Isso 进行评论功能。

1. 项目目录结构及介绍

.
├── _data                    # 存放数据文件，如用于菜单导航的数据
├── _includes                # 包含各种模板片段，用于组合成最终的网页部分
├── _layouts                 # 主题的布局文件，定义页面的基本框架
├── _posts                   # 博客文章存放位置，遵循特定命名规则
├── _sass                    # SCSS 样式文件夹，存储项目的样式定义
├── assets                   # 静态资源，如图片、JavaScript 文件等
│   ├── css                  # 编译后的 CSS 格式的样式表
│   └── js                  # 自定义 JavaScript 脚本
├── 404.html                 # 404 错误页面
├── Gemfile                  # RubyGem 配置文件，用于管理 Jekyll 相关插件和依赖
├── gitignore                # Git 忽略文件列表
├── index.html               # 主页布局或入口文件
├── README.md                # 项目介绍和使用说明文档
├── UNLICENSE.txt            # 许可证文件，声明公共领域贡献
└── _config.yml              # 项目核心配置文件

2. 项目的启动文件介绍

主要启动流程涉及到两个关键文件：index.html 和 _config.yml。

• index.html: 是站点的主入口页面，虽然这个主题可能依赖于 Jekyll 的动态布局来生成实际首页，但此文件通常包含了主页的结构和默认显示的内容。

• _config.yml: 这是配置整个 Jekyll 站点的核心文件。在这里，你可以设置站点的元信息（比如标题、作者、描述），开启或关闭特定功能（例如侧边栏、文章摘要展示），以及定制化各种高级配置，如语言设置、日期格式、布局选项等。

3. 项目的配置文件介绍

_config.yml 示例解析

title: "你的博客标题"
author: "你的名字"
description: "博客简介，介绍你的博客内容或者个人简介。"
permalink: /:title/     # 文章永久链接格式
lang: "zh-CN"          # 设置网站使用的语言
excerpt_separator: "\n\n\n"
date_format: "%B %d, %Y"  # 日期显示格式
show_excerpts: true    # 是否在首页显示文章摘要
show_frame: true       # 显示一个边框包围网站
show_sidebar: false    # 是否显示侧边栏

navigation:             # 导航栏设置
  - [file: "index.html"]
  - [file: "README.md"]

external:               # 社交链接
  - [title: "Mail", icon: envelope, url: "mailto:your-email@example.com"]
  - [title: "GitHub", icon: github, url: "https://github.com/yourusername"]

comments:               # 评论系统
  # disqus_shortname: ""
  # isso_domain: ""

plugins:                # 使用的插件
  - jekyll-feed

mathjax: true           # 启用数学公式渲染，需在文章中指定

注意：启用 MathJax 功能时，除了在 _config.yml 中设置 mathjax: true，还需确保已经正确设置了相关的前端资源加载，主题内已内置了 KaTeX 作为轻量级替代方案。

通过上述步骤，你可以快速搭建并自定义属于自己的博客，利用「Contrast」主题的强大功能和灵活性展现你的内容。记得在使用前确保本地环境已安装 Jekyll 及其必要的Ruby环境，并按照官方指示进行部署。

contrast Jekyll Theme 项目地址: https://gitcode.com/gh_mirrors/co/contrast