diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..6cc9e527 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,9 @@ +Please delete the text below before submitting your contribution. + +--- + +Thanks for contributing! If this contribution is for instructor training, please send an email to checkout@carpentries.org with a link to this contribution so we can record your progress. You’ve completed your contribution step for instructor checkout just by submitting this contribution. + +Please keep in mind that lesson maintainers are volunteers and it may be some time before they can respond to your contribution. Although not all contributions can be incorporated into the lesson materials, we appreciate your time and effort to improve the curriculum. If you have any questions about the lesson maintenance process or would like to volunteer your time as a contribution reviewer, please contact Kate Hertweck (k8hertweck@gmail.com). + +--- diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..6cc9e527 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,9 @@ +Please delete the text below before submitting your contribution. + +--- + +Thanks for contributing! If this contribution is for instructor training, please send an email to checkout@carpentries.org with a link to this contribution so we can record your progress. You’ve completed your contribution step for instructor checkout just by submitting this contribution. + +Please keep in mind that lesson maintainers are volunteers and it may be some time before they can respond to your contribution. Although not all contributions can be incorporated into the lesson materials, we appreciate your time and effort to improve the curriculum. If you have any questions about the lesson maintenance process or would like to volunteer your time as a contribution reviewer, please contact Kate Hertweck (k8hertweck@gmail.com). + +--- diff --git a/.gitignore b/.gitignore index cf3b859e..128437da 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,7 @@ .sass-cache __pycache__ _site +.Rproj.user +.Rhistory +.RData + diff --git a/.mailmap b/.mailmap index ab8458f4..afc83507 100644 --- a/.mailmap +++ b/.mailmap @@ -1,29 +1,20 @@ -James Allen -Pete Bachant -Piotr Banaszkiewicz -David Beitey -Trevor Bekolay -John Blischak -Andy Boughton -Amy Brown +Abigail Cabunoc Mayes Abigail Cabunoc Mayes -Jonah Duckles -Rémi Emonet -Ivan Gonzalez -Michael Hansen -Mike Jackson -W. Trevor King -Christina Koch -Alexander Konovalov -Francois Michonneau -Bill Mills -Aaron O'Leary -Jon Pipitone -Timothée Poisot -Florian Rathgeber +Alexander Konovalov +Amy Brown Ariel Rokem -Raniere Silva -Ashwin Srinath -Carol Willing +Bartosz Telenczuk +Erin Becker +Evan P. Williamson +François Michonneau Greg Wilson -Naupaka Zimmerman +Ivan Gonzalez +James Allen +Maxim Belkin +Mike Jackson +Raniere Silva +Raniere Silva +Rémi Emonet +Rémi Emonet +Timothée Poisot +Valentina Staneva diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000..d30f78a4 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,23 @@ +# dist: trusty # Ubuntu 14.04 +language: python +python: 3.6 +branches: + only: + - gh-pages + - /.*/ +before_install: + - sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E084DAB9 + - echo "deb https://cran.rstudio.com/bin/linux/ubuntu trusty/" | sudo tee -a /etc/apt/sources.list + - sudo apt-get update -y + - sudo apt-get install -y r-base + - sudo Rscript -e "install.packages('knitr', repos = 'https://', dependencies = TRUE)" + - sudo Rscript -e "install.packages('stringr', repos = 'https://cran.rstudio.com', dependencies = TRUE)" + - sudo Rscript -e "install.packages('checkpoint', repos = 'https://cran.rstudio.com', dependencies = TRUE)" + - sudo Rscript -e "install.packages('ggplot2', repos = 'https://cran.rstudio.com', dependencies = TRUE)" + - rvm default + - gem install json kramdown jekyll +install: + - pip install pyyaml +script: + - make lesson-check-all + - make --always-make site diff --git a/AUTHORS b/AUTHORS index c27cbadf..2d65faaa 100644 --- a/AUTHORS +++ b/AUTHORS @@ -6,24 +6,28 @@ Trevor Bekolay John Blischak Andy Boughton Amy Brown -Abigail Cabunoc Mayes +C. Titus Brown +Gerard Capes Jonah Duckles Rémi Emonet Ivan Gonzalez -Michael Hansen +Thomas Guignard +Kate Hertweck Mike Jackson W. Trevor King Christina Koch Alexander Konovalov -Francois Michonneau +François Michonneau Bill Mills Aaron O'Leary -Jon Pipitone +Bianca Peterson Timothée Poisot Florian Rathgeber Ariel Rokem Raniere Silva -Ashwin Srinath -Carol Willing +Valentina Staneva +Tracy Teal Greg Wilson +Donny Winston Naupaka Zimmerman +Bartosz Telenczuk diff --git a/CITATION b/CITATION index a3450019..b8a6d5f4 100644 --- a/CITATION +++ b/CITATION @@ -1,5 +1,5 @@ Please cite as: Greg Wilson (ed.): "Software Carpentry: Lesson Example." Version -2016.06, June 2016, https://github.com/swcarpentry/lesson-example, +2016.06, June 2016, https://github.com/carpentries/lesson-example, 10.5281/zenodo.58153. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..95d254d4 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,10 @@ +--- +title: "Contributor Code of Conduct" +--- +As contributors and maintainers of this project, +we pledge to follow the [Carpentry Code of Conduct][coc]. + +Instances of abusive, harassing, or otherwise unacceptable behavior +may be reported by following our [reporting guidelines][coc-reporting]. + +{% include links.md %} diff --git a/CONDUCT.md b/CONDUCT.md deleted file mode 100644 index e83b08fa..00000000 --- a/CONDUCT.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -layout: page -title: "Contributor Code of Conduct" -permalink: /conduct/ ---- -As contributors and maintainers of this project, -we pledge to respect all people who contribute through reporting issues, -posting feature requests, -updating documentation, -submitting pull requests or patches, -and other activities. - -We are committed to making participation in this project a harassment-free experience for everyone, -regardless of level of experience, -gender, -gender identity and expression, -sexual orientation, -disability, -personal appearance, -body size, -race, -ethnicity, -age, -or religion. - -Examples of unacceptable behavior by participants include the use of sexual language or imagery, -derogatory comments or personal attacks, -trolling, -public or private harassment, -insults, -or other unprofessional conduct. - -Project maintainers have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct. -Project maintainers who do not follow the Code of Conduct may be removed from the project team. - -Instances of abusive, harassing, or otherwise unacceptable behavior -may be reported by opening an issue or contacting one or more of the project maintainers. - -This Code of Conduct is adapted from -the [Contributor Covenant][contrib-covenant] Version 1.0.0. - -[contrib-covenant]: http://contributor-covenant.org/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c853c62..eaec89e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,27 +45,31 @@ and to meet some of our community members. ## Where to Contribute -1. If you wish to change this example lesson, - please work in . - This lesson documents the format of our lessons, - and can be viewed at . +1. If you wish to change this lesson, + please work in , + which can be viewed at . -2. If you wish to change the template used for workshop websites, - please work in . +2. If you wish to change the example lesson, + please work in , + which documents the format of our lessons + and can be viewed at . + +3. If you wish to change the template used for workshop websites, + please work in . The home page of that repository explains how to set up workshop websites, - while the extra pages in + while the extra pages in provide more background on our design choices. -3. If you wish to change CSS style files, tools, +4. If you wish to change CSS style files, tools, or HTML boilerplate for lessons or workshops stored in `_includes` or `_layouts`, - please work in . + please work in . ## What to Contribute There are many ways to contribute, from writing new exercises and improving existing ones to updating or filling in the documentation -and and submitting [bug reports][issues] +and submitting [bug reports][issues] about things that don't work, aren't clear, or are missing. If you are looking for ideas, please see [the list of issues for this repository][issues], @@ -136,13 +140,12 @@ You can also [reach us by email][contact]. [dc-lessons]: http://datacarpentry.org/lessons/ [dc-site]: http://datacarpentry.org/ [discuss-list]: http://lists.software-carpentry.org/listinfo/discuss -[example-site]: https://swcarpentry.github.io/lesson-example/ [github]: http://github.com [github-flow]: https://guides.github.com/introduction/flow/ [github-join]: https://github.com/join [how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github -[issues]: https://github.com/swcarpentry/lesson-example/issues/ -[repo]: https://github.com/swcarpentry/lesson-example/ +[issues]: https://github.com/swcarpentry/FIXME/issues/ +[repo]: https://github.com/swcarpentry/FIXME/ [swc-issues]: https://github.com/issues?q=user%3Aswcarpentry [swc-lessons]: http://software-carpentry.org/lessons/ [swc-site]: http://software-carpentry.org/ diff --git a/LICENSE.md b/LICENSE.md index 566ce553..aa088d91 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,7 +1,5 @@ --- -layout: page title: "Licenses" -permalink: /license/ --- ## Instructional Material @@ -73,11 +71,11 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ## Trademark -"Software Carpentry" an "Data Carpentry" and their respective logos -are registered trademarks of [NumFOCUS][numfocus]. +"Software Carpentry" and "Data Carpentry" and their respective logos +are registered trademarks of [Community Initiatives][CI]. [cc-by-human]: https://creativecommons.org/licenses/by/4.0/ [cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode -[mit-license]: http://opensource.org/licenses/mit-license.html -[numfocus]: http://numfocus.org/ -[osi]: http://opensource.org +[mit-license]: https://opensource.org/licenses/mit-license.html +[ci]: http://communityin.org/ +[osi]: https://opensource.org diff --git a/Makefile b/Makefile index 0f395a31..f0b73e60 100644 --- a/Makefile +++ b/Makefile @@ -4,23 +4,29 @@ # Settings MAKEFILES=Makefile $(wildcard *.mk) JEKYLL=jekyll +JEKYLL_VERSION=3.7.3 PARSER=bin/markdown_ast.rb DST=_site # Controls .PHONY : commands clean files +.NOTPARALLEL: all : commands ## commands : show all commands. commands : @grep -h -E '^##' ${MAKEFILES} | sed -e 's/## //g' +## docker-serve : use docker to build the site +docker-serve : + docker run --rm -it -v ${PWD}:/srv/jekyll -p 127.0.0.1:4000:4000 jekyll/jekyll:${JEKYLL_VERSION} make serve + ## serve : run a local server. -serve : lesson-rmd +serve : lesson-md ${JEKYLL} serve ## site : build files but do not run a server. -site : lesson-rmd +site : lesson-md ${JEKYLL} build # repo-check : check repository settings. @@ -53,7 +59,7 @@ workshop-check : ## ---------------------------------------- ## Commands specific to lesson websites. -.PHONY : lesson-check lesson-rmd lesson-files lesson-fixme +.PHONY : lesson-check lesson-md lesson-files lesson-fixme # RMarkdown files RMD_SRC = $(wildcard _episodes_rmd/??-*.Rmd) @@ -62,11 +68,11 @@ RMD_DST = $(patsubst _episodes_rmd/%.Rmd,_episodes/%.md,$(RMD_SRC)) # Lesson source files in the order they appear in the navigation menu. MARKDOWN_SRC = \ index.md \ - CONDUCT.md \ + CODE_OF_CONDUCT.md \ setup.md \ - $(wildcard _episodes/*.md) \ + $(sort $(wildcard _episodes/*.md)) \ reference.md \ - $(wildcard _extras/*.md) \ + $(sort $(wildcard _extras/*.md)) \ LICENSE.md # Generated lesson files in the order they appear in the navigation menu. @@ -74,30 +80,29 @@ HTML_DST = \ ${DST}/index.html \ ${DST}/conduct/index.html \ ${DST}/setup/index.html \ - $(patsubst _episodes/%.md,${DST}/%/index.html,$(wildcard _episodes/*.md)) \ + $(patsubst _episodes/%.md,${DST}/%/index.html,$(sort $(wildcard _episodes/*.md))) \ ${DST}/reference/index.html \ - $(patsubst _extras/%.md,${DST}/%/index.html,$(wildcard _extras/*.md)) \ + $(patsubst _extras/%.md,${DST}/%/index.html,$(sort $(wildcard _extras/*.md))) \ ${DST}/license/index.html -## lesson-rmd : convert Rmarkdown files to markdown -lesson-rmd: $(RMD_SRC) - @bin/knit_lessons.sh $(RMD_SRC) +## lesson-md : convert Rmarkdown files to markdown +lesson-md : ${RMD_DST} + +# Use of .NOTPARALLEL makes rule execute only once +${RMD_DST} : ${RMD_SRC} + @bin/knit_lessons.sh ${RMD_SRC} ## lesson-check : validate lesson Markdown. -lesson-check : - @bin/lesson_check.py -s . -p ${PARSER} +lesson-check : lesson-fixme + @bin/lesson_check.py -s . -p ${PARSER} -r _includes/links.md ## lesson-check-all : validate lesson Markdown, checking line lengths and trailing whitespace. lesson-check-all : - @bin/lesson_check.py -s . -p ${PARSER} -l -w - -## lesson-figures : re-generate inclusion displaying all figures. -lesson-figures : - @bin/extract_figures.py -p ${PARSER} ${MARKDOWN_SRC} > _includes/all_figures.html + @bin/lesson_check.py -s . -p ${PARSER} -r _includes/links.md -l -w --permissive ## unittest : run unit tests on checking tools. unittest : - python bin/test_lesson_check.py + @bin/test_lesson_check.py ## lesson-files : show expected names of generated files for debugging. lesson-files : diff --git a/README.md b/README.md index c8fa317d..8c77d55e 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ lesson-example This repository shows how to create a lesson using the [Software Carpentry lesson template][styles], and is itself an example of the use of that template. -Please see +Please see for a rendered version of this material, including detailed instructions on design, setup, and formatting. @@ -87,10 +87,11 @@ In brief: please see [the list of issues for this repository][issues]. [collections]: https://jekyllrb.com/docs/collections/ -[editing-config]: https://swcarpentry.github.io/lesson-example/03-organization/ -[example-issues]: https://github.com/swcarpentry/lesson-example/issues/ +[editing-config]: https://carpentries.github.io/lesson-example/03-organization/ +[example-issues]: https://github.com/carpentries/lesson-example/issues/ [github-pages]: https://help.github.com/articles/creating-project-pages-manually/ -[rendered]: https://swcarpentry.github.io/lesson-example/ -[setup]: https://github.com/swcarpentry/lesson-example/blob/gh-pages/setup.md -[styles-issues]: https://github.com/swcarpentry/styles/issues/ -[styles]: https://github.com/swcarpentry/styles/ +[issues]: https://github.com/carpentries/lesson-example/issues +[rendered]: https://carpentries.github.io/lesson-example/ +[setup]: https://carpentries.github.io/lesson-example/setup.html +[styles-issues]: https://github.com/carpentries/styles/issues/ +[styles]: https://github.com/carpentries/styles/ diff --git a/_config.yml b/_config.yml index a83abf27..0f3a08be 100644 --- a/_config.yml +++ b/_config.yml @@ -2,14 +2,41 @@ # Values for this lesson. #------------------------------------------------------------ -# Which carpentry is this ("swc" or "dc")? -carpentry: "swc" +# Which carpentry is this ("swc", "dc", "lc", or "cp")? +# swc: Software Carpentry +# dc: Data Carpentry +# lc: Library Carpentry +# cp: Carpentries (to use for instructor traning for instance) +carpentry: "cp" # Overall title for pages. title: "Lesson Title" -# Contact email address. -email: lessons@software-carpentry.org +#Metadata +# Here you can add metadata to describe your lesson so that people and search engines can understand what it's about. Please try to use fields from the Schema.org CreativeWork type - https://schema.org/CreativeWork +description: "This is the template description. Keep me brief (2-3 sentences)" +keywords: GitHub, Forking, Collaborative # see: https://schema.org/keywords +audience: [PostDoc students, Early Career Researchers] # see: https://schema.org/audience +license: "https://creativecommons.org/licenses/by/3.0/" # see: schema.org/license +author: [Homer Simpson, Ned Flanders] # see: https://schema.org/author +contributor: [Barney Gumball, Dr Nick Riviera] # see: https://schema.org/contributor +timeRequired: "1 hour" # see: https://schema.org/timeRequired +learningResourceType: "lesson plan" # see: https://schema.org/learningResourceType +citation: "How to cite a Training Material, John Smith et al, 2015" # see: https://schema.org/citation +dateCreated: 2016-05-01 + +#Metadata +# Here you can add metadata to describe your lesson so that people and search engines can understand what it's about. Please try to use fields from the Schema.org CreativeWork type - https://schema.org/CreativeWork +description: "This is the template description. Keep me brief (2-3 sentences)" +keywords: GitHub, Forking, Collaborative # see: https://schema.org/keywords +audience: [PostDoc students, Early Career Researchers] # see: https://schema.org/audience +license: "https://creativecommons.org/licenses/by/3.0/" # see: schema.org/license +author: [Homer Simpson, Ned Flanders] # see: https://schema.org/author +contributor: [Barney Gumball, Dr Nick Riviera] # see: https://schema.org/contributor +timeRequired: "1 hour" # see: https://schema.org/timeRequired +learningResourceType: "lesson plan" # see: https://schema.org/learningResourceType +citation: "How to cite a Training Material, John Smith et al, 2015" # see: https://schema.org/citation +dateCreated: 2016-05-01 #------------------------------------------------------------ # Generic settings (should not need to change). @@ -20,46 +47,69 @@ kind: "lesson" # Magic to make URLs resolve both locally and on GitHub. # See https://help.github.com/articles/repository-metadata-on-github-pages/. +# Please don't change it: / is correct. repository: / +# Email address, no mailto: +email: "team@carpentries.org" + # Sites. amy_site: "https://amy.software-carpentry.org/workshops" -dc_site: "https://datacarpentry.org" +carpentries_github: "https://github.com/carpentries" +carpentries_pages: "https://carpentries.github.io" +carpentries_site: "https://carpentries.org/" +dc_site: "http://datacarpentry.org" +example_repo: "https://github.com/carpentries/lesson-example" +example_site: "https://carpentries.github.io/lesson-example" +lc_site: "https://librarycarpentry.github.io/" swc_github: "https://github.com/swcarpentry" +swc_pages: "https://swcarpentry.github.io" swc_site: "https://software-carpentry.org" -template_repo: "https://github.com/swcarpentry/styles" -example_repo: "https://github.com/swcarpentry/lesson-example" -example_site: "https://swcarpentry.github.com/lesson-example" -workshop_repo: "https://github.com/swcarpentry/workshop-template" -workshop_site: "https://swcarpentry.github.io/workshop-template" +template_repo: "https://github.com/carpentries/styles" +training_site: "https://carpentries.github.io/instructor-training" +workshop_repo: "https://github.com/carpentries/workshop-template" +workshop_site: "https://carpentries.github.io/workshop-template" # Surveys. pre_survey: "https://www.surveymonkey.com/r/swc_pre_workshop_v1?workshop_id=" post_survey: "https://www.surveymonkey.com/r/swc_post_workshop_v1?workshop_id=" +training_post_survey: "https://www.surveymonkey.com/r/post-instructor-training" -# Start time in minutes (0 to be clock-independent, 540 to show a start at 09:00 am) +# Start time in minutes (0 to be clock-independent, 540 to show a start at 09:00 am). start_time: 0 # Specify that things in the episodes collection should be output. collections: episodes: output: true - permalink: /:path/ + permalink: /:path/index.html extras: output: true + permalink: /:path/index.html # Set the default layout for things in the episodes collection. defaults: + - values: + root: . + layout: page - scope: path: "" type: episodes values: + root: .. layout: episode + - scope: + path: "" + type: extras + values: + root: .. + layout: page # Files and directories that are not to be copied. exclude: - Makefile - - bin + - bin/ + - .Rproj.user/ -# Turn off built-in syntax highlighting. -highlighter: false +# Turn on built-in syntax highlighting. +highlighter: rouge diff --git a/_episodes/01-design.md b/_episodes/01-design.md index 7eb6e317..7cc741a8 100644 --- a/_episodes/01-design.md +++ b/_episodes/01-design.md @@ -9,7 +9,6 @@ objectives: - "Describe the purpose and implementation of formative assessments." keypoints: - "Lessons are design in four stages: conceptual, summative, formative, and connective." -training: http://swcarpentry.github.io/instructor-training --- This episode describes how we go about designing lessons and why. @@ -71,10 +70,9 @@ In practice, the process often looks more like this: 2. Describe the summative assessments for each half day of material (i.e., one summative assessment for a three-hour lesson and two for a full-day lesson). -3. Write a one- or two-line description of the formative assessments building up to those summative assessments. - These should be paced at roughly 15-minute intervals, - i.e., - four per hour. +3. Write a one- or two-line description of the formative assessments + building up to those summative assessments. + These should be used ideally every 5 minutes and at least every 10-15 minutes. 4. Get early feedback from peers, particularly on how realistic the time estimates are. @@ -104,8 +102,9 @@ then formative assessments should take no more than 5 minutes. This means that formative assessments should be: * multiple choice questions, -* Parsons Problems (in which the learner is given the parts of the solution in scrambled order and has to put them in the right order), -* debugging exercises (in which the learner is given a few lines of code that do the wrong thing and asked to find and fix the bug), or +* debugging exercises + (in which the learner is given a few lines of code that do the wrong thing + and asked to find and fix the bug), or * extensions of examples show in the lecture. Good formative assessments do *not* require learners to write lots of code from scratch: @@ -113,6 +112,4 @@ it takes too long, there are usually too many possible right solutions to discuss in just a couple of minutes, and many novices find a blank page (or screen) intimidating. -[concept-maps]: {{ page.training }}/07-memory/ -[python-gapminder]: https://swcarpentry.github.io/python-novice-gapminder/ -[training]: {{ page.training }}/ +{% include links.md %} diff --git a/_episodes/02-tooling.md b/_episodes/02-tooling.md index 57a1513b..dc32bffc 100644 --- a/_episodes/02-tooling.md +++ b/_episodes/02-tooling.md @@ -22,8 +22,10 @@ These simplify many tasks, but make other things more complicated. ## Repositories on GitHub Our lessons are stored in Git repositories (or "repos") on GitHub. -We use the term *fork* to mean "a copy of a GitHub-hosted repo that is also hosted on GitHub" -and the term *clone* to mean "a copy of a GitHub-hosted repo that's located on someone else's machine". +We use the term *fork* to mean +"a copy of a GitHub-hosted repo that is also hosted on GitHub" +and the term *clone* to mean +"a copy of a GitHub-hosted repo that's located on someone else's machine". In both cases, the duplicate has a reference that points to the original repo. @@ -34,7 +36,7 @@ in a template repo. The master copy of each lesson would be a fork of that repo, and each author's working copy would be a fork of that master: -![Forking Repositories](../fig/forking.svg) +![Forking Repositories]({{ page.root }}/fig/forking.svg) However, GitHub only allows a user to have one fork of any particular repo. This creates a problem for us because an author may be involved in writing several lessons, @@ -44,7 +46,7 @@ After the lesson has been created, we manually add the [template repository]({{ site.template_repo }}) as a remote called `template` to update the lesson when the template changes. -![Repository Links](../fig/repository-links.svg) +![Repository Links]({{ page.root }}/fig/repository-links.svg) ## GitHub Pages @@ -74,7 +76,7 @@ If authors want to write lessons in something else, such as [R Markdown][r-markdown], they must generate HTML or Markdown that [Jekyll][jekyll] can process and commit that to the repository. -The [next episode]({{ site.github.url }}/02-formatting/) describes the Markdown we use. +A [later episode]({{ page.root }}/04-formatting/) describes the Markdown we use. > ## Teaching Tools > @@ -113,7 +115,7 @@ this page: --- name: Science --- -Today we are going to study {{page.name}}. +{% raw %}Today we are going to study {{page.name}}.{% endraw %} ~~~ {: .source} @@ -121,12 +123,12 @@ is translated into: ~~~ - -

Today we are going to study Science.

- + +

Today we are going to study Science.

+ ~~~ -{: .source} +{: .html} > ## Back in the Day... > @@ -162,14 +164,6 @@ putting the extra files in `_extras` allows us to populate the "Extras" menu pul To clarify what will appear where, we store files that appear directly in the navigation bar in the root directory of the lesson. -[The last episode]({{ site.github.url }}/03-organization/) describes these files. - -[github-importer]: https://import.github.com/ -[jekyll]: http://jekyllrb.com/ -[jekyll-collection]: https://jekyllrb.com/docs/collections/ -[jekyll-install]: https://jekyllrb.com/docs/installation/ -[jupyter]: https://jupyter.org/ -[pandoc]: https://pandoc.org/ -[r-markdown]: http://rmarkdown.rstudio.com/ -[rstudio]: https://www.rstudio.com/ -[yaml]: http://yaml.org/ +[The next episode]({{ page.root }}/03-organization/) describes these files. + +{% include links.md %} diff --git a/_episodes/03-organization.md b/_episodes/03-organization.md index d54f9a91..74b8683f 100644 --- a/_episodes/03-organization.md +++ b/_episodes/03-organization.md @@ -14,8 +14,8 @@ keypoints: - "The Makefile stores commonly-used commands." --- -Each lesson is made up of *episodes* that are 10-30 minutes long -(including time for both teaching and exercises). +Each lesson is made up of *episodes*, which are focused on a particular topic and +include time for both teaching and exercises. The episodes of this lesson explain the tools we use to create lessons and the formatting rules those lessons must follow. @@ -38,11 +38,11 @@ Instead, each lesson's repository is self-contained. The diagram below shows how source files and directories are laid out, and how they are mapped to destination files and directories: -![Source and Destination Files](../fig/file-mapping.svg) +![Source and Destination Files]({{ page.root }}/fig/file-mapping.svg) > ## Collections > -> As described [earlier]({{ site.github.url }}/02-tooling/#collections), +> As described [earlier]({{ page.root }}/02-tooling/#collections), > files that appear as top-level items in the navigation menu are stored in the root directory. > Files that appear under the "extras" menu are stored in the `_extras` directory, > while lesson episodes are stored in the `_episodes` directory. @@ -78,114 +78,94 @@ which should *not* be modified: ## Starter Files -The `bin/lesson_initialize.py` script creates files that need to be customized for each lesson. - -### `CONTRIBUTING.md` - -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}`. - -### `_config.yml` - -The [Jekyll][jekyll] configuration file. -This must be edited so that its links and other settings are correct for this lesson. - -* `carpentry` should be either "dc" (for Data Carpentry) or "swc" (for Software Carpentry). - -* `title` is the title of your lesson, +The `bin/lesson_initialize.py` script creates files that need to be customized for each lesson: + +`CONTRIBUTING.md` +: 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 `FIXME`. + +`_config.yml` +: The [Jekyll][jekyll] configuration file. + This must be edited so that its links and other settings are correct for this lesson. + * `carpentry` should be either "dc" (for Data Carpentry) or "swc" (for Software Carpentry). + * `title` is the title of your lesson, + e.g., + "Defence Against the Dark Arts". + * `email` is the contact email address for the lesson. + +`CITATION` +: A plain text file explaining how to cite this lesson. + +`AUTHORS` +: A plain text file listing the names of the lesson's authors. + +`index.md` +: The home page for the lesson. + 1. It must use the `lesson` layout. + 2. It must *not* have a `title` field in its [YAML][yaml] header. + 3. It must open with a few paragraphs of explanatory text. + 4. That introduction must be followed by a single `.prereq` blockquote + detailing the lesson's prerequisites. + (Setup instructions appear separately.) + 5. That must be followed by inclusion of `syllabus.html`, + which generates the syllabus for the lesson + from the metadata in its episodes. + +`reference.md` +: A reference guide for the lesson. + The template will automatically generate a summary of the episodes' key points. + 1. It must use the `reference` layout. + 2. Its title must be `"Reference"`. + 3. Its permalink must be `/reference/`. + 4. It should include a glossary, laid out as a description list. + 5. It may include other material as appropriate. + +`setup.md` +: Detailed setup instructions for the lesson. + Note that we usually divide setup instructions by platform, e.g., - "Defence Against the Dark Arts". - -* `email` is the contact email address for the lesson. - -### `CITATION` - -A plain text file explaining how to cite this lesson. - -### `AUTHORS` - -A plain text file listing the names of the lesson's authors. - -### `index.md` - -The home page for the lesson. - -1. It must use the `index` layout. -2. It must *not* have a `title` field in its [YAML][yaml] header. -3. It must open with a few paragraphs of explanatory text. -4. That introduction must be followed by a single `.prereq` blockquote - detailing the lesson's prerequisites. - (Setup instructions appear separately.) -5. That must be followed by inclusion of `syllabus.html`, - which generates the syllabus for the lesson - from the metadata in its episodes. - -### `reference.md` - -A reference guide for the lesson. - -1. It must use the `reference` layout. -2. Its title must be `"Reference"`. -3. Its permalink must be `/reference/`. -4. It should include a glossary, laid out as a description list. -5. It may include other material as appropriate. - -The template will automatically generate a summary of the episodes' key points. - -### `setup.md` - -Detailed setup instructions for the lesson. - -1. It must use the `page` layout. -2. Its title must be `"Setup"`. -3. Its permalink must be `/setup/`. -4. It should include whatever setup instructions are required. - -Note that we usually divide setup instructions by platform, -e.g., -include level-2 headings for Windows, Mac OS X, and Linux -with instructions for each. -The [workshop template]({{ site.workshop_repo }}) -links to the setup instructions for core lessons. - -### `_extras/about.md` - -General notes about this lesson. -This page includes brief descriptions of Software Carpentry and Data Carpentry, -and is a good place to put institutional acknowledgments. - -### `_extras/discussion.md` - -General discussion of the lesson contents for learners who wish to know more: - -1. It must use the `page` layout. -2. Its title must be `"Discussion"`. -3. Its permalink must be `/discuss/`. -4. It may include whatever content the author thinks appropriate. - -This page normally includes links to further reading -and/or brief discussion of more advanced topics. - -### `_extra/figures.md` and `_includes/all_figures.html` - -Does nothing but include `_includes/all_figures.html`, -which is (re)generated by `make lesson-figures`. -This page displays all the images referenced by all of the episodes, -in order, -so that instructors can scroll through them while teaching. - -### `_extras/guide.md` - -The instructors' guide for the lesson. - -1. It must use the `page` layout. -2. Its title must be `"Instructors' Guide"`. -3. Its permalink must be `/guide/`. -4. It may include whatever content the author thinks appropriate. - -This page records tips and warnings from people who have taught the lesson. - -[jekyll]: http://jekyllrb.com/ -[jekyll-collection]: https://jekyllrb.com/docs/collections/ + include level-2 headings for Windows, Mac OS X, and Linux + with instructions for each. + The [workshop template]({{ site.workshop_repo }}) + links to the setup instructions for core lessons. + 1. It must use the `page` layout. + 2. Its title must be `"Setup"`. + 3. Its permalink must be `/setup/`. + 4. It should include whatever setup instructions are required. + +`_extras/about.md` +: General notes about this lesson. + This page includes brief descriptions of Software Carpentry and Data Carpentry, + and is a good place to put institutional acknowledgments. + +`_extras/discussion.md` +: General discussion of the lesson contents for learners who wish to know more: + This page normally includes links to further reading + and/or brief discussion of more advanced topics. + 1. It must use the `page` layout. + 2. Its title must be `"Discussion"`. + 3. Its permalink must be `/discuss/`. + 4. It may include whatever content the author thinks appropriate. + +`_extra/figures.md` and `_includes/all_figures.html` +: Does nothing but include `_includes/all_figures.html`, + which is (re)generated by `make lesson-figures`. + This page displays all the images referenced by all of the episodes, + in order, + so that instructors can scroll through them while teaching. + +`_extras/guide.md` +: The instructors' guide for the lesson. + This page records tips and warnings from people who have taught the lesson. + 1. It must use the `page` layout. + 2. Its title must be `"Instructors' Guide"`. + 3. Its permalink must be `/guide/`. + 4. It may include whatever content the author thinks appropriate. + +## Figures + +All figures related with the lesson **must** be placed inside the directory `fig` at the root of the project. + +{% include links.md %} diff --git a/_episodes/04-formatting.md b/_episodes/04-formatting.md index 449b6855..df266e9c 100644 --- a/_episodes/04-formatting.md +++ b/_episodes/04-formatting.md @@ -13,7 +13,7 @@ keypoints: - "Lesson episodes are stored in _episodes/dd-subject.md." - "Each episode's title must include a title, time estimates, motivating questions, lesson objectives, and key points." - "Episodes should not use sub-headings or HTML layout." -- "Code blocks can be have the source, regular output, or error class." +- "Code blocks can have the source, regular output, or error class." - "Special sections are formatted as blockquotes that open with a level-2 header and close with a class identifier." - "Special sections may be callouts or challenges; other styles are used by the template itself." --- @@ -28,11 +28,25 @@ each of which has: The diagram below shows the internal structure of a single episode file (click on the image to see a larger version): -Formatting Rules + + Formatting Rules + + +## Maximum Line Length + +Limit all lines to a maximum of 100 characters. +`bin/lesson_check.py` will report lines longer than 100 characters +and this can block your contributions of being accepted. + +The two reasons behind the decision to enforce a maximum line lenght are +(1) make diff and merge easier in the command line and other user interfaces +and +(2) make update of translation of the lessons easier. ## Locations and Names Episode files are stored in `_episodes` +or, for the case of R Markdown files, `_episodes_rmd` so that [Jekyll][jekyll] will create a [collection][jekyll-collection] for them. Episodes are named `dd-subject.md`, where `dd` is a two-digit sequence number (with a leading 0) @@ -47,13 +61,10 @@ in the published site. When referring to other episodes, use: {% raw %} - [link text]({{ site.github.url }}/dd-subject/) + [link text]({{ page.root }}{% link _episodes/dd-subject.md %}) {% endraw %} -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. +i.e., use [Jekyll's tag link](https://jekyllrb.com/docs/templates/#links) and the name of the file. ## Episode Header @@ -95,6 +106,17 @@ Authors should *not* use: * sub-headings * HTML layout (e.g., `div` elements). + +> ## Linking section IDs +> +> In the HTML output each header of a section, code sample, exercise will be associated with an unique ID (the rules of +> the ID generation are given in kramdown [documentation](https://kramdown.gettalong.org/converter/html.html#auto-ids), +> but it is easier to look for them directly in the page sources). +> These IDs can be used to easily link to the section by attaching the hash (`#`) followed by the ID to the page's URL +> (like [this](#linking-section-ids)). For example, the instructor might copy the link to +> the etherpad, so that the lesson opens in learners' web browser directly at the right spot. +{: .callout} + ## Formatting Code Inline code fragments are formatted using back-quotes. @@ -137,23 +159,70 @@ The [template]({{ site.template_repo }}) provides three styles for code blocks: ~~~ {: .error} -The following styles are all synonyms for `.source`; -please use them where possible to indicate the type of source being displayed, -in case we decide to adopt syntax highlighting at some point: +### Syntax Highlighting + +The following styles like `.source`, but include syntax highlighting for the +specified language. +Please use them where possible to indicate the type of source being displayed, +and to make code easier to read. + +`.language-bash`: Bash shell commands: + +~~~ +echo "Hello World" +~~~ +{: .language-bash} + +`.html`: HTML source: + +~~~ + + +Hello World + + +~~~ +{: .html} + +`.language-make`: Makefiles: + +~~~ +all: + g++ main.cpp hello.cpp -o hello +~~~ +{: .language-make} + +`.language-matlab`: MATLAB source: + +~~~ +disp('Hello, world!') +~~~ +{: .language-matlab} + +`.language-python`: Python source: + +~~~ +print("Hello World") +~~~ +{: .language-python} + +`.language-r`: R source: + +~~~ +cat("Hello World") +~~~ +{: .language-r} + +`.language-sql`: SQL source: + +~~~ +CREATE PROCEDURE HelloWorld AS +PRINT 'Hello, world!' +RETURN (0) +~~~ +{: .language-sql} -* `.bash`: Bash shell commands -* `.make`: Makefiles -* `.matlab`: MATLAB source -* `.python`: Python source -* `.r`: R source -* `.sql`: SQL source -> ## Why No Syntax Highlighting? -> -> We do not use syntax highlighting for code blocks -> because some learners' systems won't do it, -> or will do it differently than what they see on screen. -{: .callout} ## Special Blockquotes @@ -202,7 +271,7 @@ for the following special blockquotes:
-> ## .callout +> ## `.callout` > > An aside or other comment. {: .callout} @@ -262,7 +331,8 @@ but is used to prevent the checking tools from complaining about a missing class Most authors will only use `.callout`, `.challenge`, and `.prereq`, as the others are automatically generated by the template. -Note that `.prereq` is meant for describing things that learners should know before starting this lesson; +Note that `.prereq` is meant for describing things +that learners should know before starting this lesson; setup instructions do not have a particular style, but are instead put on the `setup.md` page. @@ -303,6 +373,4 @@ but the alternatives we considered and discarded are worse: but clutters up the page and makes it harder for tools to tell which solutions belong to which exercises. -[jekyll]: http://jekyllrb.com/ -[jekyll-collection]: https://jekyllrb.com/docs/collections/ -[yaml]: http://yaml.org/ +{% include links.md %} diff --git a/_episodes/06-rmarkdown-example.md b/_episodes/05-rmarkdown-example.md similarity index 51% rename from _episodes/06-rmarkdown-example.md rename to _episodes/05-rmarkdown-example.md index 7be5e082..07cc3edb 100644 --- a/_episodes/06-rmarkdown-example.md +++ b/_episodes/05-rmarkdown-example.md @@ -1,4 +1,5 @@ --- +source: Rmd title: "Using RMarkdown" teaching: 10 exercises: 2 @@ -10,15 +11,32 @@ objectives: keypoints: - "It shouldn't be difficult" --- + This episode demonstrates all the features that can be used when writing a -lesson in RMarkdown. +lesson in [RMarkdown][r-markdown]. + +To generate the site, you will need to have the following packages installed: + + +```r +install.packages(c("knitr", "stringr", "checkpoint")) +``` + +If the lesson uses additional packages, the script that converts the Rmd files +into markdown, will detect them and install them for you, when you run `make +serve` or `make site`. -This first chunk is really important, and should be included in all markdown lessons. +This first chunk is really important, and need to be included at the beginning of +each episode written in RMarkdown. +~~~ +source("../bin/chunk-options.R") +~~~ +{: .language-r} The rest of the lesson should be written as a normal RMarkdown file. You can -include chunk for codes, just like you'd normally do: +include chunk for codes, just like you'd normally do. Normal output: @@ -26,7 +44,7 @@ Normal output: ~~~ 1 + 1 ~~~ -{: .r} +{: .language-r} @@ -41,7 +59,7 @@ Output with error message: ~~~ x[10] ~~~ -{: .r} +{: .language-r} @@ -55,46 +73,59 @@ Output generating figures: ~~~ library(ggplot2) -~~~ -{: .r} - - - -~~~ -Warning: package 'ggplot2' was built under R version 3.1.3 -~~~ -{: .error} - - - -~~~ ggplot(diamonds, aes(x = carat, y = price, color = cut)) + geom_point() ~~~ -{: .r} +{: .language-r} plot of chunk plot-example -For the challenges and their solutions, you need to pay attention to the where -the `>` go and where to leave blank lines. Otherwise, you can include chunks in -it to include instructions and solutions. +For the challenges and their solutions, you need to pay attention to where the +`>` go and where to leave blank lines. You can include code chunks in both the +instructions and solutions. For instance this: + +``` +> ## Challenge: Can you do it? +> +> What is the output of this command? +> +> +> ~~~ +> paste("This", "new", "template", "looks", "good") +> ~~~ +> {: .language-r} +> +> > ## Solution +> > +> > +> > ~~~ +> > [1] "This new template looks good" +> > ~~~ +> > {: .output} +> {: .solution} +{: .challenge} +``` + +will generate this: > ## Challenge: Can you do it? > > What is the output of this command? > -> +> > ~~~ > paste("This", "new", "template", "looks", "good") > ~~~ -> {: .r} +> {: .language-r} > > > ## Solution > > -> > +> > > > ~~~ > > [1] "This new template looks good" > > ~~~ > > {: .output} > {: .solution} {: .challenge} + +{% include links.md %} diff --git a/_episodes/06-style-guide.md b/_episodes/06-style-guide.md new file mode 100644 index 00000000..9ea55877 --- /dev/null +++ b/_episodes/06-style-guide.md @@ -0,0 +1,176 @@ +--- +title: "Style Guide" +teaching: 10 +exercises: 0 +questions: +- "How are keyboard key combinations written?" +objectives: +- "Explain keyboard key combination." +keypoints: +- "Keyboard keys need to use `` HTML tag." +--- + +## Emphasis + +Markdown treats asterisks (_*_) indicators of emphasis, +and renders text marked up like this in italics. +We use emphasis + +- to highlight a word, phrase, or character where it is itself the object of discussion. + + For example, + + ~~~ + We want to output the lines that do not contain the word *the*. + ~~~ + + This is preferable instead of the use of quotation marks. + + See the "Keyboard Key" section for characters or keyboard keys that the learn should type. + +- for words and phrases that are still regarded as unfamiliar. +- for titles of books, periodicals, plays, films, TV, radio series, and music albums. + + For example, + + ~~~ + We will use a file that contains three haikus taken from a 1998 competition in *Salon* magazine. + ~~~ + +## Strong Emphasis + +Markdown treats double asterisks (_**_) as indicators of strong emphasis, +and renders text marked up like this in boldface. +We use strong emphasis + +- to highlight a newly introduced term, often one that is going to be defined or explained. + For example, + + ~~~ + We are all familiar with **graphical user interfaces** + ~~~ + +## Span of Code + +Markdown treats backtick quotes (_\`_) as indicators of a span of code. +We use span of code + +- to highlight part of some code where it is itself the object of discussion. + + For example, + + ~~~ + For example, `range(3, 10, 2)` produces + ~~~ +- to highlight one command where it is itself the object of discussion. + + For example, + + ~~~ + you can run it by opening a terminal and typing `bash`. + ~~~ + + When the object of discussion is the program or language in a broad sense, + we don't use span of code. For example, + + ~~~ + The most popular Unix shell is Bash. + ~~~ +- to highlight one function where it is itself the object of discussion. + + For example, + + ~~~ + `len` is much faster than any function we could write ourselves. + ~~~ +- to highlight one file name where it is itself the object of discussion. + + For example, + + ~~~ + `my_file.txt` can also be viewed in your GUI file explorer. + ~~~ +- to highlight any sequence of character that the user is expected to type. + +## Keyboard Key + +When making reference to a keyboard key that the reader should press +the HTML tag `` **must** be used to enclose the key label. +For example, "to delete the cell press D" should be write as + +~~~ +to delete the cell press D +~~~ +{: .html} + +The table below covers most of the keyboard key labels. + +|-------------------+--------------------------------------------------------------------+--------------------------| +| Keyboard key | Style Note | Example | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Letters | Always capital. | `A` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Numbers | | `1` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Punctuation mark | | `*` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Function | Capital F followed by the number. | `F12` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Alt | Only first letter capital. | `Alt` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Backspace | Only first letter capital. | `Backspace` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Ctrl | Only first letter capital. | `Ctrl` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Delete | Only first letter capital. | `Delete` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| End | Only first letter capital. | `End` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Esc | Only first letter capital. | `Esc` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Home | Only first letter capital. | `Home` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Insert | Only first letter capital. | `Insert` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Page Down | Use "PgDn". | `PgDn` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Page Up | Use "PgUp". | `PgUp` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Print Screen | Use "PtrScr". | `PtrScr` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Return | Only first letter capital. We use "Return" instead of "Enter". | `Return` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Shift | Only first letter capital. | `Shift` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Spacebar | Only first letter capital. | `Spacebar` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Tab | Only first letter capital. | `Tab` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Down arrow | Use Unicode "Downwards arrow" (8595). | `↓` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Left arrow | Use Unicode "Leftwards arrow" (8592). | `←` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Right arrow | Use Unicode "Rightwards arrow" (8594). | `→` | +|-------------------+--------------------------------------------------------------------+--------------------------| +| Up arrow | Use Unicode "Upwards arrow" (8593). | `↑` | +|-------------------+--------------------------------------------------------------------+--------------------------| + +## Keyboard Key Combination + +When making reference to a keyboard key combination that the reader should press, +insert a plus sign **without space** between each one of the keys. +For example, "press Ctrl+X to quit nano" should be written as: + +~~~ +press Ctrl+X to quit nano. +~~~ +{: .html} + + +## Links + +Please label links with meaningful texts, in order to [improve +accessibility](https://webaccess.berkeley.edu/ask-pecan/click-here). Please avoid +`click here` or similar. + +{% include links.md %} diff --git a/_episodes/05-checking.md b/_episodes/07-checking.md similarity index 83% rename from _episodes/05-checking.md rename to _episodes/07-checking.md index 11218538..4fa6186a 100644 --- a/_episodes/05-checking.md +++ b/_episodes/07-checking.md @@ -24,7 +24,7 @@ You can run this using `make lesson-check`, which in turn invokes `bin/markdown_ast.rb` to parse Markdown files and `bin/lesson_check.py` to check their structure. The former is written in Ruby, -and uses Jekyll's own Markdown parser (called Kramdown) +and uses [Jekyll][jekyll]'s own Markdown parser (called [Kramdown][kramdown]) so that we are guaranteed to be checking the same dialect of Markdown that Jekyll uses on GitHub. The latter is written in Python 3, and executes all of the checks. @@ -52,11 +52,6 @@ Run `make` on its own to get a full list of commands. In order to use Jekyll and/or the checking script, you may need to install it and some other software. -The [setup instructions]({{ site.github.url }}/setup/) explain what you need and how to get it. +The [setup instructions]({{ page.root }}{% link setup.md %}#optional-jekyll-setup-for-lesson-development) explain what you need and how to get it. -## Displaying Figures - -The command `make lesson-figures` uses the script `bin/make_figures.py` -to regenerate `includes/all_figures.html`, -which links to every figure used in the episodes (in order). -Instructors can scroll through this page to display figures while teaching. +{% include links.md %} diff --git a/_episodes/07-maintenance.md b/_episodes/07-maintenance.md deleted file mode 100644 index aa6f3f00..00000000 --- a/_episodes/07-maintenance.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: "Maintenance" -teaching: 5 -exercises: 0 -questions: -- "What do lesson maintainers do?" -objectives: -- "Explain the rights and responsibilities of lesson maintainers." -keypoints: -- "Each lesson has one or two maintainers who act as editors." -- "Maintainers are responsible for ensuring that issues and change requests are addressed." -- "Maintainers have final say over lesson content." ---- - -This episode describes the processes used to maintain our lessons. - -## Maintainers - -Each Software or Data Carpentry lesson has one or two maintainers, -who are responsible for making sure issues and change requests are looked at, -and who have final say over what is included in the lesson. -Together, -they also decide on changes to the lesson templates, -release procedure, -and other mechanical aspects of lesson production. -They are *not* responsible for writing lesson content or deciding what lessons ought to exist: -the former comes from the community, -and the latter from the Executive Directors and Steering Committees of Software and Data Carpentry. - -The process for selecting and onboarding a new maintainer is: - -* Outgoing maintainer emails the discussion list to announce the opportunity - * Application information includes name, github username, statement of intent. - * Deadline for applications, projected timeline for selection. - * Name/email of contact for application process (typically outgoing maintainer). -* Applications accumulate over a week or two. -* Outgoing maintainer and their co-maintainer review applications and choose new maintainer. -* The new maintainer is informed, and other applicants are thanked via email. -* To onboard the new maintainer: - * Add new maintainer to the maintainers' list. - * Email the maintainers to announce the change. - * Request push/merge access for new maintainer from the Software or Data Carpentry executive director. - * Write a blog post introducing new maintainer. - * Optional: call between outgoing/incoming maintainer to discuss state of the repository, transition strategy, etc. - -## Release Process and Schedule - -We have decided to use a **6-month release cycle** for releases, which -will be named by the year and month they happen, e.g., `2016.05`. - -1. Each lesson lives in the `gh-pages` branch of its own repository. -2. When a release has to be made, - the *lesson maintainer* (or maintainers) create a branch named after the release, e.g., `2016.05`. -3. A *release maintainer* generates HTML pages for that release and add them to the branch. -4. If there isn't already a directory for that release in the `swc-release` repository, - the release maintainer creates one - and adds an `index.html` page to it. -5. The release maintainer adds a submodule to the release directory of `swc-release` - that points to the newly-created release branch of the lesson. diff --git a/_episodes/08-coffee.md b/_episodes/08-coffee.md index 21ed662a..3129b250 100644 --- a/_episodes/08-coffee.md +++ b/_episodes/08-coffee.md @@ -7,3 +7,5 @@ break: 15 Use the `break` layout for placeholder episodes representing coffee breaks and lunches. These episodes do *not* have exercises, questions, objectives, or keypoints in their metadata, but *must* have a "break" field to show how long the break is (in minutes). + +{% include links.md %} diff --git a/_episodes_rmd/05-rmarkdown-example.Rmd b/_episodes_rmd/05-rmarkdown-example.Rmd new file mode 100644 index 00000000..b7aec20f --- /dev/null +++ b/_episodes_rmd/05-rmarkdown-example.Rmd @@ -0,0 +1,99 @@ +--- +source: Rmd +title: "Using RMarkdown" +teaching: 10 +exercises: 2 +questions: +- "How to write a lesson using RMarkdown?" +objectives: +- "Explain how to use RMarkdown with the new lesson template." +- "Demonstrate how to include pieces of code, figures, and challenges." +keypoints: +- "Edit the .Rmd files not the .md files" +- "Run `make serve` to knit documents and preview lesson website locally" +--- + +This episode demonstrates all the features that can be used when writing a +lesson in [RMarkdown][r-markdown]. + +To generate the site, you will need to have the following packages installed: + +```{r, eval=FALSE} +install.packages(c("knitr", "stringr", "checkpoint")) +``` + +If the lesson uses additional packages, the script that converts the Rmd files +into markdown, will detect them and install them for you, when you run `make +serve` or `make site`. + +This first chunk is really important, and need to be included at the beginning of +each episode written in RMarkdown. + +```{r, echo=TRUE} +source("../bin/chunk-options.R") +``` + +The rest of the lesson should be written as a normal RMarkdown file. You can +include chunk for codes, just like you'd normally do. + +Normal output: + +```{r} +1 + 1 +``` + +Output with error message: + +```{r} +x[10] +``` + +Output generating figures: + +```{r plot-example} +library(ggplot2) +ggplot(diamonds, aes(x = carat, y = price, color = cut)) + + geom_point() +``` + +For the challenges and their solutions, you need to pay attention to where the +`>` go and where to leave blank lines. You can include code chunks in both the +instructions and solutions. For instance this: + +``` +> ## Challenge: Can you do it? +> +> What is the output of this command? +> +> ```{r, eval=FALSE} +> paste("This", "new", "template", "looks", "good") +> ``` +> +> > ## Solution +> > +> > ```{r, echo=FALSE} +> > paste("This", "new", "template", "looks", "good") +> > ``` +> {: .solution} +{: .challenge} +``` + +will generate this: + +> ## Challenge: Can you do it? +> +> What is the output of this command? +> +> ```{r, eval=FALSE} +> paste("This", "new", "template", "looks", "good") +> ``` +> +> > ## Solution +> > +> > ```{r, echo=FALSE} +> > paste("This", "new", "template", "looks", "good") +> > ``` +> {: .solution} +{: .challenge} + +{% include links.md %} diff --git a/_episodes_rmd/06-rmarkdown-example.Rmd b/_episodes_rmd/06-rmarkdown-example.Rmd deleted file mode 100644 index 801896c3..00000000 --- a/_episodes_rmd/06-rmarkdown-example.Rmd +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Using RMarkdown" -teaching: 10 -exercises: 2 -questions: -- "How to write a lesson using RMarkdown?" -objectives: -- "Explain how to use RMarkdown with the new lesson template." -- "Demonstrate how to include pieces of code, figures, and challenges." -keypoints: -- "It shouldn't be difficult" ---- -This episode demonstrates all the features that can be used when writing a -lesson in RMarkdown. - -This first chunk is really important, and should be included in all markdown lessons. - -```{r, echo=FALSE} -source("../bin/chunk-options.R") -``` - -The rest of the lesson should be written as a normal RMarkdown file. You can -include chunk for codes, just like you'd normally do: - -Normal output: - -```{r} -1 + 1 -``` - -Output with error message: - -```{r} -x[10] -``` - -Output generating figures: - -```{r plot-example} -library(ggplot2) -ggplot(diamonds, aes(x = carat, y = price, color = cut)) + - geom_point() -``` - -For the challenges and their solutions, you need to pay attention to the where -the `>` go and where to leave blank lines. Otherwise, you can include chunks in -it to include instructions and solutions. - -> ## Challenge: Can you do it? -> -> What is the output of this command? -> -> ```{r, eval=FALSE} -> paste("This", "new", "template", "looks", "good") -> ``` -> -> > ## Solution -> > -> > ```{r, echo=FALSE} -> > paste("This", "new", "template", "looks", "good") -> > ``` -> {: .solution} -{: .challenge} diff --git a/_extras/about.md b/_extras/about.md index aa7beea3..718fdfde 100644 --- a/_extras/about.md +++ b/_extras/about.md @@ -1,6 +1,5 @@ --- -layout: page title: About -permalink: /about/ --- + {% include carpentries.html %} diff --git a/_extras/discuss.md b/_extras/discuss.md index 118633f7..e7906d57 100644 --- a/_extras/discuss.md +++ b/_extras/discuss.md @@ -1,14 +1,11 @@ --- -layout: page title: Discussion -permalink: /discuss/ --- + Readers may be interested in: * PeerJ's [paper-now], which uses [Jekyll][jekyll] as a framework for writing scientific papers. * The [Morea Framework][morea], a more elaborate template for [Jekyll][jekyll]-based lessons. -[jekyll]: http://jekyllrb.com/ -[morea]: https://morea-framework.github.io/ -[paper-now]: https://github.com/PeerJ/paper-now +{% include links.md %} diff --git a/_extras/figures.md b/_extras/figures.md index de99a578..b807e484 100644 --- a/_extras/figures.md +++ b/_extras/figures.md @@ -1,6 +1,38 @@ --- -layout: page title: Figures -permalink: /figures/ --- -{% include all_figures.html %} + +{% comment %} +Create anchor for each one of the episodes. +{% endcomment %} +{% for episode in site.episodes %} +
+{% endfor %} diff --git a/_extras/guide.md b/_extras/guide.md index 7e3bb719..de8d505d 100644 --- a/_extras/guide.md +++ b/_extras/guide.md @@ -1,8 +1,37 @@ --- -layout: page -title: "Instructors' Guide" -permalink: /guide/ +title: "Instructor Notes" --- -Discussion of the lesson aimed at instructors would normally go here, -but since this is just an example, -there isn't much to say. + +The instructor notes should provide additional discussion useful to instructors, +but not appropriate for inclusion in the main lessons. The following structure +provides a consistent way for instructors to both prepare for a workshop and +quickly find necessary information during a workshop. + +Please remember not to overload on details, and to keep the comments here positive! + +## Lesson motivation and learning objectives + +These concepts should be highlighted in the main lesson material, but ideas for +explaining these concepts further can be placed here. + +## Lesson design + +Most lessons contain more material than can be taught in a single workshop. +Describe a general narrative (with time estimates) for teaching either a half day +or full day with this lesson material. You may also choose to include multiple +options for lesson design, or what material can be skipped while teaching. +This section may also include recommendations for how this lesson fits into +the overall workshop. + +## Technical tips and tricks + +Provide information on setting up your environment for learners to view your +live coding (increasing text size, changing text color, etc), as well as +general recommendations for working with coding tools to best suit the +learning environment. + +## Common problems + +This can include answers to common learner questions, as well as links to +resources (blog posts, stack overflow answers, etc) that may solve problems that +may occur during a workshop. diff --git a/_includes/all_figures.html b/_includes/all_figures.html deleted file mode 100644 index fc116258..00000000 --- a/_includes/all_figures.html +++ /dev/null @@ -1,13 +0,0 @@ -

-
-

Forking Repositories

-
-

Repository Links

-
-

Source and Destination Files

-
-

Formatting Rules

-
-

-
-

plot of chunk plot-example

diff --git a/_includes/all_keypoints.html b/_includes/all_keypoints.html index e2c901c2..8563df34 100644 --- a/_includes/all_keypoints.html +++ b/_includes/all_keypoints.html @@ -7,7 +7,7 @@

Key Points

{% unless episode.break %} - {{ episode.title }} + {{ episode.title }}
    diff --git a/_includes/carpentries.html b/_includes/carpentries.html index a233117a..4d5c9060 100644 --- a/_includes/carpentries.html +++ b/_includes/carpentries.html @@ -1,6 +1,9 @@ +{% comment %} + General description of Software and Data Carpentry. +{% endcomment %}
    - Software Carpentry logo + Software Carpentry logo
    Since 1998, @@ -14,7 +17,7 @@
    - Data Carpentry logo + Data Carpentry logo
    Data Carpentry develops and teaches workshops on the fundamental data skills needed to conduct research. @@ -23,5 +26,19 @@ building on learners' existing knowledge to enable them to quickly apply skills learned to their own research.
    - - +
    +
    +
    + Library Carpentry logo +
    +
    + Library Carpentry is made by librarians to help librarians + automate repetitive, boring, error-prone tasks; + create, maintain and analyse sustainable and reusable data; + work effectively with IT and systems colleagues; + better understand the use of software in research; + and much more. + Library Carpentry was the winner of the 2016 + British Library Labs Teaching and Learning Award. +
    +
    diff --git a/_includes/dc/intro.html b/_includes/dc/intro.html new file mode 100644 index 00000000..741aeebb --- /dev/null +++ b/_includes/dc/intro.html @@ -0,0 +1,18 @@ +

    + Data Carpentry + aims to help researchers get their work done + in less time and with less pain + by teaching them basic research computing skills. + This hands-on workshop will cover basic concepts and tools, + including program design, version control, data management, + and task automation. + Participants will be encouraged to help one another + and to apply what they have learned to their own research problems. +

    +

    + + For more information on what we teach and why, + please see our paper + "Best Practices for Scientific Computing". + +

    diff --git a/_includes/dc/schedule.html b/_includes/dc/schedule.html new file mode 100644 index 00000000..6894a19e --- /dev/null +++ b/_includes/dc/schedule.html @@ -0,0 +1,24 @@ +
    +
    +

    Day 1

    + + + + + + + +
    09:00 Automating tasks with the Unix shell
    10:30 Coffee
    12:00 Lunch break
    13:00 Building programs with Python
    14:30 Coffee
    16:00 Wrap-up
    +
    +
    +

    Day 2

    + + + + + + + +
    09:00 Version control with Git
    10:30 Coffee
    12:00 Lunch break
    13:00 Managing data with SQL
    14:30 Coffee
    16:00 Wrap-up
    +
    +
    diff --git a/_includes/dc/syllabus.html b/_includes/dc/syllabus.html new file mode 100644 index 00000000..a325ceec --- /dev/null +++ b/_includes/dc/syllabus.html @@ -0,0 +1,96 @@ +
    +
    +

    The Unix Shell

    +
      +
    • Files and directories
      • +
    • History and tab completion
      • +
    • Pipes and redirection
      • +
    • Looping over files
      • +
    • Creating and running shell scripts
      • +
    • Finding things
      • +
    • Reference...
      • +
    +
    +
    +

    Programming in Python

    +
      +
    • Using libraries
      • +
    • Working with arrays
      • +
    • Reading and plotting data
      • +
    • Creating and using functions
      • +
    • Loops and conditionals
      • +
    • Defensive programming
      • +
    • Using Python from the command line
      • +
    • Reference...
      • +
    +
    + + +
    + +
    +
    +

    Version Control with Git

    +
      +
    • Creating a repository
      • +
    • Recording changes to files: add, commit, ...
      • +
    • Viewing changes: status, diff, ...
      • +
    • Ignoring files
      • +
    • Working on the web: clone, pull, push, ...
      • +
    • Resolving conflicts
      • +
    • Open licenses
      • +
    • Where to host work, and why
      • +
    • Reference...
      • +
    +
    + +
    +

    Open Refine

    +
      +
    • Introduction to OpenRefine
      • +
    • Importing data
      • +
    • Basic functions
      • +
    • Advanced Functions
      • +
    • Reference...
      • +
    +
    +
    diff --git a/_includes/dc/who.html b/_includes/dc/who.html new file mode 100644 index 00000000..2d8e94ae --- /dev/null +++ b/_includes/dc/who.html @@ -0,0 +1,8 @@ +

    + Who: + The course is aimed at graduate students and other researchers. + + You don't need to have any previous knowledge of the tools + that will be presented at the workshop. + +

    diff --git a/_includes/episode_break.html b/_includes/episode_break.html index 81fd39e8..36d2d2fa 100644 --- a/_includes/episode_break.html +++ b/_includes/episode_break.html @@ -1,4 +1,15 @@ {% comment %} - Display information about a break. + Display a break's timings in a box similar to a learning episode's. {% endcomment %} -

    Break: {{page.break}} min

    +
    +

    Overview

    + +
    +
    + Break: {{ page.break }} min +
    +
    +
    +
    + +
    diff --git a/_includes/episode_keypoints.html b/_includes/episode_keypoints.html index 85378a56..2baa53ef 100644 --- a/_includes/episode_keypoints.html +++ b/_includes/episode_keypoints.html @@ -1,3 +1,6 @@ +{% comment %} + Display key points for an episode. +{% endcomment %}

    Key Points

      diff --git a/_includes/episode_navbar.html b/_includes/episode_navbar.html new file mode 100644 index 00000000..c2bc80e8 --- /dev/null +++ b/_includes/episode_navbar.html @@ -0,0 +1,28 @@ +{% comment %} + Navigation bar for an episode. +{% endcomment %} +
      +
      +

      + {% if page.previous.url %} + previous episode + {% else %} + lesson home + {% endif %} +

      +
      +
      + {% if include.episode_navbar_title %} +

      {{ site.title }}

      + {% endif %} +
      +
      +

      + {% if page.next.url %} + next episode + {% else %} + lesson home + {% endif %} +

      +
      +
      diff --git a/_includes/episode_overview.html b/_includes/episode_overview.html index f22a1a69..cb87e0f6 100644 --- a/_includes/episode_overview.html +++ b/_includes/episode_overview.html @@ -7,7 +7,7 @@

      Overview

      Teaching: {{ page.teaching }} min -
      +
      Exercises: {{ page.exercises }} min
      @@ -19,7 +19,7 @@

      Overview

    - +
    @@ -32,5 +32,5 @@

    Overview

- + diff --git a/_includes/episode_title.html b/_includes/episode_title.html index 7ea24a26..d0abc654 100644 --- a/_includes/episode_title.html +++ b/_includes/episode_title.html @@ -1,46 +1,9 @@ -{% comment %} - Find previous and next episodes (if any). -{% endcomment %} -{% for episode in site.episodes %} - {% if episode.url == page.url %} - {% unless forloop.first %} - {% assign prev_episode = prev %} - {% endunless %} - {% unless forloop.last %} - {% assign next_episode = site.episodes[forloop.index] %} - {% endunless %} - {% endif %} - {% assign prev = episode %} -{% endfor %} - -{% comment %} - Display title and prev/next links. -{% endcomment %}
-

- {% if prev_episode %} - - {% elsif site.github.url %} - - {% else %} - - {% endif %} -

-

{{ site.title }}

{{ page.title }}

-

- {% if next_episode %} - - {% elsif site.github.url %} - - {% else %} - - {% endif %} -

diff --git a/_includes/favicons.html b/_includes/favicons.html new file mode 100644 index 00000000..4ea6742d --- /dev/null +++ b/_includes/favicons.html @@ -0,0 +1,33 @@ +{% assign favicon_url = site.baseurl | append: '/assets/favicons/' | append: site.carpentry | prepend: site.url %} + +{% if site.carpentry == 'swc' %} +{% assign carpentry = 'Software Carpentry' %} +{% elsif site.carpentry == 'dc' %} +{% assign carpentry = 'Data Carpentry' %} +{% elsif site.carpentry == 'lc' %} +{% assign carpentry = 'Library Carpentry' %} +{% elsif site.carpentry == 'cp' %} +{% assign carpentry = 'The Carpentries' %} +{% endif %} + + + + + + + + + + + + + + + + + + + + + + diff --git a/_includes/javascript.html b/_includes/javascript.html index ccf0a887..a2066c20 100644 --- a/_includes/javascript.html +++ b/_includes/javascript.html @@ -1,3 +1,14 @@ - - - +{% comment %} + Javascript used in lesson and workshop pages. +{% endcomment %} + + + + diff --git a/_includes/lc/intro.html b/_includes/lc/intro.html new file mode 100644 index 00000000..a4a53eca --- /dev/null +++ b/_includes/lc/intro.html @@ -0,0 +1,19 @@ +

+ Library Carpentry + is made by librarians, for librarians to help you: +

+
    +
  • automate repetitive, boring, error-prone tasks
    • +
  • create, maintain and analyse sustainable and reusable data
    • +
  • work effectively with IT and systems colleagues
    • +
  • better understand the use of software in research
    • +
  • and much more...
    • +
+

+ + Library Carpentry introduces you to the fundamentals of computing + and provides you with a platform for further self-directed learning. + For more information on what we teach and why, please see our paper + "Library Carpentry: software skills training for library professionals". + +

diff --git a/_includes/lc/schedule.html b/_includes/lc/schedule.html new file mode 100644 index 00000000..cc2b5920 --- /dev/null +++ b/_includes/lc/schedule.html @@ -0,0 +1,24 @@ +
+
+

Day 1

+ + + + + + + +
09:00 Data Intro for Librarians
10:30 Coffee
12:00 Lunch break
13:00 Shell Lessons for Libraries
14:30 Coffee
16:00 Wrap-up
+
+
+

Day 2

+ + + + + + + +
09:00 Git Intro for Librarians
10:30 Coffee
12:00 Lunch break
13:00 OpenRefine for Librarians
14:30 Coffee
16:00 Wrap-up
+
+
diff --git a/_includes/lc/syllabus.html b/_includes/lc/syllabus.html new file mode 100644 index 00000000..e2c7012e --- /dev/null +++ b/_includes/lc/syllabus.html @@ -0,0 +1,69 @@ +
+
+

Data Intro

+
    +
  • Intro to data
    • +
  • Jargon busting
    • +
  • Keyboard shortcuts
    • +
  • Plain text formats
    • +
  • Naming files
    • +
  • Regular expressions
    • +
  • Reference...
    • +
+
+
+

The Unix Shell

+
    +
  • Files and directories
    • +
  • History and tab completion
    • +
  • Counting and sorting contents in files
    • +
  • Pipes and redirection
    • +
  • Mining or searching in files
    • +
  • Reference...
    • +
+
+ +
+ +
+
+

Version Control with Git

+
    +
  • Creating a repository
    • +
  • Configuring git
    • +
  • Recording changes to files: add, commit, ...
    • +
  • Viewing state changes with status
    • +
  • Working on the web: clone, pull, push, ...
    • +
  • Where to host work, and why
    • +
  • Reference...
    • +
+
+
+
+

Open Refine

+
    +
  • Introduction to OpenRefine
    • +
  • Importing data
    • +
  • Basic functions
    • +
  • Advanced Functions
    • +
  • Reference...
    • +
+
+
+
+ diff --git a/_includes/lc/who.html b/_includes/lc/who.html new file mode 100644 index 00000000..fd9b38c4 --- /dev/null +++ b/_includes/lc/who.html @@ -0,0 +1,8 @@ +

+ Who: + The course is for librarians, archivists, and other information workers. + + You don't need to have any previous knowledge of the tools that + will be presented at the workshop. + +

diff --git a/_includes/lesson_footer.html b/_includes/lesson_footer.html index 58d08fae..7df84da7 100644 --- a/_includes/lesson_footer.html +++ b/_includes/lesson_footer.html @@ -1,21 +1,51 @@ -
+{% comment %} + Footer for lesson pages. +{% endcomment %} diff --git a/_includes/links.md b/_includes/links.md new file mode 100644 index 00000000..8a27ab30 --- /dev/null +++ b/_includes/links.md @@ -0,0 +1,39 @@ +[cc-by-human]: https://creativecommons.org/licenses/by/4.0/ +[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode +[ci]: http://communityin.org/ +[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html#reporting-guidelines +[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html +[concept-maps]: https://carpentries.github.io/instructor-training/05-memory/ +[contrib-covenant]: https://contributor-covenant.org/ +[contributing]: {{ site.github.repository_url }}/blob/gh-pages/CONTRIBUTING.md +[cran-checkpoint]: https://cran.r-project.org/package=checkpoint +[cran-knitr]: https://cran.r-project.org/package=knitr +[cran-stringr]: https://cran.r-project.org/package=stringr +[email]: mailto:team@carpentries.org +[github-importer]: https://import.github.com/ +[importer]: https://github.com/new/import +[jekyll-collection]: https://jekyllrb.com/docs/collections/ +[jekyll-install]: https://jekyllrb.com/docs/installation/ +[jekyll-windows]: http://jekyll-windows.juthilo.com/ +[jekyll]: https://jekyllrb.com/ +[jupyter]: https://jupyter.org/ +[kramdown]: https://kramdown.gettalong.org/ +[lesson-example]: https://carpentries.github.io/lesson-example/ +[mit-license]: https://opensource.org/licenses/mit-license.html +[morea]: https://morea-framework.github.io/ +[numfocus]: https://www.numfocus.org/ +[osi]: https://opensource.org +[pandoc]: https://pandoc.org/ +[paper-now]: https://github.com/PeerJ/paper-now +[python-gapminder]: https://swcarpentry.github.io/python-novice-gapminder/ +[pyyaml]: https://pypi.python.org/pypi/PyYAML +[r-markdown]: https://rmarkdown.rstudio.com/ +[rstudio]: https://www.rstudio.com/ +[ruby-install-guide]: https://www.ruby-lang.org/en/downloads/ +[ruby-installer]: https://rubyinstaller.org/ +[rubygems]: https://rubygems.org/pages/download/ +[styles]: https://github.com/carpentries/styles/ +[swc-releases]: https://github.com/swcarpentry/swc-releases +[training]: https://carpentries.github.io/instructor-training/ +[workshop-repo]: {{ site.workshop_repo }} +[yaml]: http://yaml.org/ diff --git a/_includes/main_title.html b/_includes/main_title.html index 06019b93..d007abae 100644 --- a/_includes/main_title.html +++ b/_includes/main_title.html @@ -1 +1,4 @@ -

{{ site.title }}{% if page.title %}: {{ page.title }}{% endif %}

+{% comment %} + Main title for lesson pages. +{% endcomment %} +

{{ site.title }}{% if page.title %}: {{ page.title }}{% endif %}

diff --git a/_includes/navbar.html b/_includes/navbar.html index b5dafb46..868bce8d 100644 --- a/_includes/navbar.html +++ b/_includes/navbar.html @@ -1,3 +1,6 @@ +{% comment %} + Lesson navigation bar. +{% endcomment %}