diff --git a/_episodes/01-tooling.md b/_episodes/01-tooling.md index 58b8eb79860af3f8a0dad52a907d1d27c6b33648..2a2526e1bd60a599ce37daab6710b1a7585dbe30 100644 --- a/_episodes/01-tooling.md +++ b/_episodes/01-tooling.md @@ -49,13 +49,14 @@ to update the lesson when the template changes. If a repository has a branch called `gh-pages` (short for "GitHub Pages"), GitHub publishes its content to create a website for the repository. -Websites can be static HTML pages, +If the repository's URL is `https://github.com/USERNAME/REPOSITORY`, +the website is `https://USERNAME.github.io/REPOSITORY`. + +GitHub Pages sites can include static HTML pages, which are published as-is, -or can use [Jekyll][jekyll] as described below +or they can use [Jekyll][jekyll] as described below to compile HTML and/or Markdown pages with embedded directives to create the pages for display. -If the repository's URL is `https://github.com/USERNAME/REPOSITORY`, -the website is `https://USERNAME.github.io/REPOSITORY`. > ## Why Doesn't My Site Appear? > @@ -63,8 +64,6 @@ the website is `https://USERNAME.github.io/REPOSITORY`. > GitHub will *not* generate a website for that repository's `gh-pages` branch. {: .callout} -## Markdown - We write lessons in Markdown because it's simple to learn and isn't tied to any specific language. (The ReStructured Text format popular in the Python world, @@ -88,8 +87,7 @@ The [next episode]({{ site.root }}/02-formatting/) describes the Markdown we use ## Jekyll GitHub uses [Jekyll][jekyll] to turn Markdown into HTML. -By default, -it looks for text files that begin with a header formatted like this: +It looks for text files that begin with a header formatted like this: ~~~ --- @@ -100,13 +98,32 @@ other_variable: other_value ~~~ {: .source} -and inserts the values of those variables into the page when formatting this. +and inserts the values of those variables into the page when formatting it. The three dashes that start the header *must* be the first three characters in the file: even a single space before them will make [Jekyll][jekyll] ignore the file. -The header must be formatted as [YAML][yaml], +The header's content must be formatted as [YAML][yaml], and may contain Booleans, numbers, character strings, lists, and dictionaries of name/value pairs. Values from the header are referred to in the page as `page.variable`. +For example, +this page: + +~~~ +--- +name: Science +--- +Today we are going to study {{page.name}}. +~~~ + +is translated into: + +~~~ + + +

Today we are going to study Science.

+ + +~~~ > ## Back in the Day... > @@ -126,9 +143,9 @@ The [lesson template]({{ site.template_repo }}) does *not* include `_config.yml` since each lesson will change some of its value, which would result in merge collisions each time the lesson was updated from the template. Instead, -the [template]({{ site.template_repo }}) contains `_templates/_config_template.yml`; -authors should copy this file to create `_config.yml` -and then edit values in the top half. +the [template]({{ site.template_repo }}) contains a script called `bin/initialize` +which should be run *once* to create an initial `_config.yml` file. +The author should then edit the values in the top half of the file. The [template]({{ site.template_repo }}) also contains `_config_dev.yml`, which overrides some settings for use during desktop development. @@ -144,10 +161,10 @@ We rely on this for both lesson episodes (stored in `_episodes`) and extra files (stored in `_extras`). For example, putting the extra files in `_extras` allows us to populate the "Extras" menu pulldown automatically. -To make this clear, +To clarify what will appear where, we store files that appear directly in the navigation bar -(rather than under a pulldown menu) in the root directory of the lesson. +[The last episode]({{ site.root }}/03-organization/) describes these files. ## Installing @@ -170,15 +187,14 @@ for full instructions. to compile source files into HTML pages in the `_site` directory, or to do that and also run a small web server at so that the pages can be previewed. -We strongly recommend using the latter, -since it ensures that inter-page links will work -and extra resources (such as glyph icons) will load properly. +We recommend using the latter, +since it gives a more accurate impression of what your lesson will actually look like. -The Makefile in the root directory of the project has commands for doing both: +The Makefile in the root directory of the project contains commands for building the site. `make site` builds files but does not run a server, while `make serve` builds the files and runs a server. (It also re-builds the site whenever it notices changes in the source files.) -Run `make` on its own to get a list of commands. +Run `make` on its own to get a full list of commands. [github-importer]: https://import.github.com/ [jekyll]: http://jekyllrb.com/ diff --git a/_episodes/02-formatting.md b/_episodes/02-formatting.md index a15d8ceee6e9faa198be3971642aa8b4da01dd28..672f5255b685c636037578da34921d5d9b58c787 100644 --- a/_episodes/02-formatting.md +++ b/_episodes/02-formatting.md @@ -40,15 +40,15 @@ the episodes of this example lesson are `_episodes/01-tooling.md` `_episodes/02-formatting.md`, and `_episodes/03-organization.md`. -These become `/01-tooling/`, `/02-formatting/`, and `/03-organization/` respectively in the published site -(the episode file `dd-subject.md` is turned into `dd-subject/index.html`). +These become `/01-tooling/index.html`, `/02-formatting/index.html`, and `/03-organization/index.html` in the published site. When referring to other episodes, use: {% raw %} [link text]({{ site.root }}/dd-subject/) {% endraw %} -i.e., use the episode's directory path below the site root. +i.e., use the episode's directory path below the site root +*without* the `index.html` (which the web server fills in automatically). This will ensure that the link is valid both when previewing during desktop development and when the site is published on GitHub. diff --git a/_episodes/03-organization.md b/_episodes/03-organization.md index 93483fdbef5a29325cce1a3a3d917085451d4dc2..9ca1c6c04be4cc0462d917481b8afc748022a580 100644 --- a/_episodes/03-organization.md +++ b/_episodes/03-organization.md @@ -50,6 +50,10 @@ Authors should not modify these. ## Standard Files +When the lesson repository is first created, +the initial author should create a `README.md` file containing +a one-line explanation of the lesson's purpose. + The [lesson template]({{ site.template_repo }}) provides the following files which should *not* be modified: @@ -57,38 +61,30 @@ which should *not* be modified: * `LICENSE.md`: the lesson license. * `Makefile`: commands for previewing the site, cleaning up junk, etc. -## Template Files - -The `_templates` directory contains files that need to be customized for each lesson: +## Starter Files -* `CONTRIBUTING.md`: contribution guidelines. - This file should be copied into the root directory, - and the `issues` and `repo` links at the bottom of the file must be changed - to match the URLs of the lesson. -* `_config.yml`: [Jekyll][jekyll] configuration file. - As explained [earlier]({{ site.root }}/01-tooling/#configuration), - `_templates/_config.yml` must be copied into the root directory - and edited so that its links and other settings are correct for this lesson. +The `bin/initialize` script creates files that need to be customized for each lesson. -## Common Files +### `CONTRIBUTING.md` -Most lessons will contain the files listed below. -These are *not* included in the template in order to avoid repeated merge conflicts. +Contribution guidelines. +The `issues` and `repo` links at the bottom of the file must be changed +to match the URLs of the lesson: +look for uses of `{LESSON-NAME}`. -### `README.md` +### `_config.yml` -A brief description of the lesson that is displayed by GitHub. -This file does *not* include a [YAML][yaml] header, -and is *not* included in the generated website. +The [Jekyll][jekyll] configuration file. +This must be edited so that its links and other settings are correct for this lesson: +look for uses of `{USERNAME}`, `{LESSON-NAME}`, `{LESSON-TITLE}`, and `{SITE-NAME}`. -### `AUTHORS` +### `CITATION` -The names and email addresses of authors, one per line. -This file provides a more convenient way to view contributors than walking the Git history. +A plain text file explaining how to cite this lesson. -### `CITATION` +### `AUTHORS` -This explains how the lesson should be cited in publications. +A plain text file listing the names and email addresses of the lesson's authors. ### `index.md` @@ -155,10 +151,5 @@ The instructors' guide for the lesson. This page records tips and warnings from people who have taught the lesson. -## Makefile Targets - -Commonly-used commands are stored in `Makefile`. -Run `make` on its own to get a list of commands. - [jekyll]: http://jekyllrb.com/ [jekyll-collection]: https://jekyllrb.com/docs/collections/ diff --git a/bin/initialize b/bin/initialize index 3ab2b9dc370ef9efe19829324b912e4521f45239..51640922533507594a413bb71d6e78ed28da87ce 100755 --- a/bin/initialize +++ b/bin/initialize @@ -7,6 +7,14 @@ import sys import os +ROOT_AUTHORS = '''\ +FIXME: list authors' names and email addresses. +''' + +ROOT_CITATION = '''\ +FIXME: describe how to cite this lesson. +''' + ROOT_CONTRIBUTING_MD = '''\ # Contributing @@ -243,6 +251,8 @@ FIXME ''' BOILERPLATE = ( + ('AUTHORS', ROOT_AUTHORS), + ('CITATION', ROOT_CITATION), ('CONTRIBUTING.md', ROOT_CONTRIBUTING_MD), ('_config.yml', ROOT_CONFIG_YML), ('index.md', ROOT_INDEX_MD),