Carpentries工作坊模板

这个仓库是Carpentries（Software Carpentry、Data Carpentry和Library Carpentry）用于创建工作坊网站的模板。

1. **请不要直接在GitHub上fork这个仓库。**相反，请按照以下说明使用GitHub的"模板"功能复制这个workshop-template仓库，并为你的工作坊进行定制。

2. 请在你仓库的gh-pages分支上进行工作，因为这是GitHub自动发布为网站的分支。

3. 完成后，请告诉我们工作坊的URL。如果这是一个自组织的工作坊，你还应该填写自组织工作坊表格（如果你还没有这样做），以便我们能够跟踪所有工作坊。我们根据你的index.md页面中包含的数据在我们的网站上构建工作坊列表。只有当你正确地定制该页面并且让我们知道工作坊URL时，我们才能做到这一点。

如果你遇到问题，或者有关于如何简化这个过程的想法，请联系我们。定制你的网站、FAQ和设计说明页面有更多关于我们做什么和为什么这样做的详细信息。请注意：如果你正在教授Git，请为学习者创建一个单独的仓库供他们练习。

视频教程

有一个YouTube视频演示了如何创建工作坊网站。

创建仓库

1. 登录GitHub。（如果你没有账号，可以快速免费创建一个。）你必须登录才能完成接下来的步骤。

2. 在此页面（https://github.com/carpentries/workshop-template）上，点击右上角的绿色"Use this template"按钮。

   或者，使用此链接：使用此模板。在下拉按钮中选择"Create a new repository"。

3. 为你的新仓库选择所有者。（这可能是你，也可能是你所属的组织。）

4. 使用Carpentries的slug格式命名你的工作坊网站仓库。slug应该采用YYYY-MM-DD-site的形式，例如2016-12-01-oomza，其中YYYY-MM-DD是工作坊的开始日期，'oomza'是一个示例站点名称。如果你的工作坊在线上举行，那么仓库名称应该以-online结尾，例如2016-12-01-oomza-online。确保你的slug不以-或_字符结尾。如果你的仓库名称不符合有效的slug格式，你的网站构建将会失败！

5. 确保仓库是公开的，取消勾选"Include all branches"，然后点击"Create repository from template"。你将被重定向到你新复制的工作坊模板仓库。

6. 你的新网站将在https://your_username.github.io/YYYY-MM-DD-site渲染。例如，如果你的用户名是gvwilson，网站的URL将是https://gvwilson.github.io/2016-12-01-oomza。

如果你遇到问题，请联系我们。

定制你的网站（必要步骤）

有两种方式可以定制你的网站。你可以：

• 直接在GitHub上使用网页浏览器编辑文件
• 在你的计算机上克隆仓库并在本地更新文件

在网页浏览器中更新GitHub上的文件

1. 进入你新创建的仓库，地址为https://github.com/your_username/YYYY-MM-DD-site。例如，如果你的用户名是gvwilson，仓库的URL将是https://github.com/gvwilson/2016-12-01-oomza。

2. 通过点击菜单栏下拉菜单中的分支，确保你在gh-pages分支上（见下面的注释）：

   

3. 编辑index.md的标题以自定义讲师列表、工作坊地点等。你可以通过在GitHub的文件视图中点击它，然后选择菜单栏中的铅笔图标在浏览器中进行编辑：

   

   编辑提示嵌入在index.md中，完整说明在定制说明中。

4. 删除index.md文件中关于使用工作坊模板的通知。你可以安全地删除从{% comment %}到{% endcomment %}（包括在内）之间的所有内容，如下所示（从第35行到第58行）：

   {% comment %} <------------ 从这行开始删除
   8< ============= 对于工作坊，从这里删除 =============
   对于工作坊，请删除以下块，直到下一个虚线
   {% endcomment %}
   
   <div class="alert alert-danger">
     ....
   </div>
   
   {% comment %}
    8< ============================= 删除到这里 ==================
   {% endcomment %} <--------- 删除到这行

5. 编辑_config.yml以自定义某些网站范围的变量，如：carpentry（告诉参与者你的工作坊的课程项目），curriculum和flavor（你的工作坊教授的课程），以及title（所有页面的总标题）。

   编辑提示嵌入在_config.yml中，完整说明在定制说明中。

6. 编辑schedule.html文件以编辑你即将举行的工作坊的日程安排。这个文件位于_includes目录中，确保选择适当的dc（Data Carpentry工作坊）、lc（Library Carpentry）或swc（Software Carpentry）子目录中的文件。

在本地工作

注意：如果你已经使用网页界面更新了你的网站，你就不需要这样做了。

如果你已经熟悉Git，你可以将仓库克隆到你的桌面，按照上面的说明编辑index.md、_config.yml和schedule.html，然后将你的更改推送回仓库。

git clone https://github.com/your_username/YYYY-MM-DD-site

为了在完成编辑后查看你的更改，如果你已安装bundler（见下面的安装说明），你可以使用以下命令在本地预览你的网站：

make serve

然后访问http://0.0.0.0:4000预览你的网站。

在将更改推送到你的仓库之前，我们建议你也通过运行以下命令检查你的网站是否存在任何潜在问题：

make workshop-check

一旦你对网站的编辑感到满意，将更改提交并推送到你的仓库。

几分钟后，你就可以访问你的工作坊网站的GitHub Pages URL并预览它了。在上面的例子中，这个URL是https://gvwilson.github.io/2016-12-01-oomza。完成的页面应该看起来像这样。

可选但推荐的步骤

更新你的仓库描述并链接你的网站

在GitHub上你的仓库顶部，你会看到

未提供描述、网站或主题。— 编辑

点击"编辑"并添加：

1. 在"描述"框中添加你的工作坊的简短描述（例如，"Oomza大学工作坊，2016年12月"）

2. 在"网站"框中添加你的工作坊的URL（例如，https://gvwilson.github.io/2016-12-01-oomza）

这将帮助人们在访问你的仓库主页时找到你的网站。你可能想勾选"使用GitHub pages链接"的复选框。

更新README文件的内容

你可以更改网站仓库中的README.md文件，它包含这些说明，使其包含你的工作坊的简短描述和工作坊网站的链接。

其他注意事项

注意： 请在你仓库的gh-pages分支中完成所有工作，因为GitHub会自动将其发布为网站。

注意： 这个模板包含了一些大多数工作坊不需要的文件和目录，但它们为额外内容提供了一个标准位置（如果需要的话）。 更多信息请参见设计说明。

更多说明可在定制说明中找到。 这个FAQ包含一些额外的提示（欢迎添加）， 这些关于背景和设计的说明也可能有所帮助。

创建额外页面

在罕见的情况下，你可能想要为你的工作坊网站添加额外的页面。 你可以通过在网站的根目录中放置Markdown或HTML页面来实现这一点， 并按照课程模板中给出的说明进行样式设置。

安装软件

如果你想设置Jekyll以便在推送到GitHub之前在自己的机器上预览更改， 你必须安装课程示例设置说明中描述的软件。

为学习者设置单独的仓库

如果你在教授Git， 你应该为学习者创建一个单独的仓库供他们在那节课中使用。 你不应该让他们使用工作坊网站仓库，因为：

• 你的工作坊网站仓库包含许多大多数学习者在课程中不需要看到的文件，而且

• 你可能不希望在使用它来教学时，不小心将来自新手Git用户的可能有害的拉取请求合并到你的工作坊网站中。

你可以随意命名这个仓库，并添加你需要的任何内容。

获取和提供帮助

我们致力于为我们的学习者和组织者提供愉快的设置体验。 如果你在我们的说明中发现错误， 或想要提出改进建议， 请提交问题 或给我们发邮件。