使用 Reveal.js 和 Git 创建 Web 教程

无论您是学习者还是教师，您可能都认识到在线研讨会（设置为幻灯片形式以交流知识）的价值。如果您曾经偶然发现过这些组织良好的教程，它们是逐页、逐章节设置的，您可能想知道创建这样一个网站有多难。

在这里，我将向您展示使用完全自动化的流程生成此类研讨会是多么容易。

简介

当我开始将我的学习内容放到网上时，体验并不流畅。因此，我想要一些可重复且一致的东西，而且还要易于维护，因为我的内容会随着我教授的技术的进步而变化。

我尝试了许多交付模型，从低级代码生成器（例如 Asciidoctor）到将研讨会布局在单个 PDF 文件中。所有这些都未能让我满意。当我进行现场研讨会时，我喜欢使用幻灯片，所以我想知道我是否可以为我的在线、自定进度的研讨会体验做同样的事情。

经过一番研究，我为创建轻松的研讨会网站打下了基础。这得益于我已经在使用一个演示文稿生成框架，该框架生成了网站友好的格式 (HTML)。

设置

以下是此项目所需的基本组件

研讨会想法（这是您的问题，我无能为力）
用于研讨会幻灯片的 Reveal.js
GitLab 项目仓库
您最喜欢的 HTML 代码编辑器
Web 浏览器
安装在您机器上的 Git

如果这个列表看起来令人生畏，那么有一种快速入门的方法，无需将所有部分逐一拼凑在一起：您可以使用我的模板项目，让您快速开始幻灯片和项目设置。

本文假设您熟悉 Git 和托管在 GitLab 等 Git 平台上的项目。如果您需要复习或教程，请查看我们的 Git 入门系列。

首先将模板项目克隆到您的本地机器

$ git clone https://gitlab.com/eschabell/beginners-guide-automated-workshops.git

为此设置一个新的 GitLab 项目，并将模板项目作为初始导入导入。

研讨会网站有许多重要的文件。在根目录中，您会找到一个名为 .gitlab-ci.yml 的文件，当您将更改提交到主分支时（即，将拉取请求合并到 master）会将其用作触发器。它触发将 slides 目录的完整内容复制到 GitLab 项目的 website 文件夹中。

我将其托管在我的 GitLab 帐户中，项目名为 beginners-guide-automated-workshops。部署后，您可以通过导航到以下网址在浏览器中查看 slides 目录的内容

https://eschabell.gitlab.io/beginners-guide-automated-workshops

对于您的用户帐户和项目，URL 看起来像

https://[YOUR_USERNAME].gitlab.io/[YOUR_PROJECT_NAME]

这些是您开始创建网站内容所需的基本材料。当您推送更改时，它们将自动生成您更新后的研讨会网站。请注意，默认模板包含几个示例幻灯片，这将是您完成完整签入到存储库后的第一个研讨会网站。

研讨会模板生成一个 reveal.js 幻灯片，可以在任何浏览器中运行，并具有自动调整大小功能，几乎任何人、任何地方、任何设备都可以查看它。

这种创建方便且易于访问的研讨会的方式怎么样？

工作原理

有了这个背景，您就可以探索研讨会材料并开始将您的内容组合在一起。您需要的一切都可以在项目的 slides 目录中找到；这就是 reveal.js 发挥魔力以在浏览器中创建研讨会幻灯片的地方。

您将用于制作研讨会的文件和目录是

default.css 文件
images 目录
index.html 文件

在您最喜欢的 HTML/CSS 编辑器中打开每个文件，并进行以下描述的更改。您使用哪个编辑器并不重要；我更喜欢 RubyMine IDE，因为它在本地浏览器中提供页面预览。这在我将内容推送到在线研讨会网站之前测试内容时很有帮助。

Default.css 文件

文件 css/theme/default.css 是您将在其中设置研讨会幻灯片的重要全局设置的基础文件。两个主要的关注点是所有幻灯片的默认字体和背景图像。

在 default.css 中，查看标记为 GLOBAL STYLES 的部分。当前默认字体在行中列出

font-family: "Red Hat Display", "Overpass", san-serif;

如果您使用非标准字体类型，则必须在行中导入它（就像为 Overpass 字体类型所做的那样）

@import url('SOME_URL');

background 是您创建的每个幻灯片的默认图像。它存储在 images 目录中（见下文），并在下面的行中设置（关注图像路径）

background: url("…/…/images/backgrounds/basic.png")

要设置默认背景，只需将此行指向您要使用的图像即可。

Images 目录

顾名思义，images 目录用于存储您要在研讨会幻灯片上使用的图像。例如，我通常会将演示研讨会主题进度的屏幕截图放在我的各个幻灯片上。

现在，您只需知道您需要将背景图像存储在子目录 (backgrounds) 中，并将您计划在幻灯片中使用的图像存储在 Images 目录中。

Index.html 文件

现在您已经整理好这两个文件，您将花费剩余的时间在 HTML 文件中创建幻灯片，从 index.html 开始。为了使您的研讨会网站开始成形，请注意此文件中的以下三个部分

head 部分，您可以在其中设置标题、作者和描述
body 部分，您可以在其中找到要设计的各个幻灯片
每个 section，您可以在其中定义各个幻灯片的内容

从 head 部分开始，因为它位于顶部。模板项目有三个占位符行供您更新

<title>INSERT-YOUR-TITLE-HERE</title>
<meta name="description" content="YOUR DESCIPTION HERE.">
<meta name="author" content="YOUR NAME">

title 标签包含文件打开时在浏览器选项卡中显示的文本。将其更改为与您的研讨会标题（或研讨会的某个部分）相关的内容，但请记住保持简短，因为选项卡标题空间有限。description 元标记包含您的研讨会的简短描述，而 author 元标记是您应该输入您的姓名（或研讨会创建者的姓名，如果您是为其他人做这件事）的地方。

现在转到 body 部分。您会注意到它分为多个 section 标签。body 的开头包含一条注释，解释说您正在为每个标记为 section 的开始和结束标签创建幻灯片

<body>
	<div class="reveal">

	<!-- Any section element inside of this container is displayed as a slide -->
	<div class="slides">

接下来，创建您的各个幻灯片，每个幻灯片都包含在 section 标签中。该模板包含一些幻灯片，以帮助您入门。例如，这是第一张幻灯片

<section>
      <div style="width: 1056px; height: 300px">
            <h1>Beginners guide</h1>
            <h2>to automated workshops</h2>
      </div>
      <div style="width: 1056px; height: 200px; text-align: left">
            Brought to you by,<br/>
            YOUR-NAME<br/>
      </div>
      <aside class="notes">Here are notes: Welcome to the workshop!</aside>
</section>

此幻灯片有两个区域，用 div 标签分隔。间距分隔标题和作者。

假设您具备使用 HTML 的一些知识，请尝试各种方法来开发您的研讨会。在您进行预览结果时使用浏览器非常方便。某些 IDE 提供对更改的本地查看，但您也可以打开 index.html 文件并在将其推送到存储库之前查看您的更改。

一旦您对您的研讨会感到满意，请推送您的更改，并等待它们通过持续集成管道。它们将像模板项目一样托管在 https://eschabell.gitlab.io/beginners-guide-automated-workshops。