diff --git a/pages/01-one.md b/01-one.md similarity index 100% rename from pages/01-one.md rename to 01-one.md diff --git a/pages/02-two.md b/02-two.md similarity index 100% rename from pages/02-two.md rename to 02-two.md diff --git a/DESIGN.md b/DESIGN.md index b5fd710e61c716aa0a345bdf2ab9ad23fb726002..cde70fe8b78d6698ea22cea5d315c6ff7dfebd59 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -56,16 +56,20 @@ this template is organized the way it is: 6. Using Pandoc instead of Jekyll means that we have to compile our Markdown into HTML on our own machines and commit it to the - `gh-pages` branch of the lesson's GitHub repository. In order to - keep our source files and generated files separate, we put our - source files in a sub-directory called `pages`, and compile them - "upward" into the root directory of the lesson's repository. + `gh-pages` branch of the lesson's GitHub repository. - **Note:** while it's usually considered bad practice to put - computer-generated files under version control, the HTML pages put - into the lesson's root directory by Pandoc *must* be committed to - version control in order for the lesson to be displayed properly - on GitHub. + It's considered bad practice to put computer-generated files under + version control, but the HTML pages put into the lesson's root + directory by Pandoc *must* be committed to version control in + order for the lesson to be displayed properly on GitHub. + + It's also considered bad practice to put generated files in the + same directory as source files. We do it because some source + files, such as R Markdown and IPython Notebook files, are + executable, and contain paths to things like images and data + files. If we put our source files in a sub-directory, those paths + won't work (or conversely, if we put our generated files in a + different directory, the paths won't work there). 7. In order to display properly, our generated HTML pages need artwork, CSS style files, and a few bits of Javascript. We could @@ -76,6 +80,6 @@ this template is organized the way it is: One final note: we try not to put HTML inside Markdown because it's ugly to read and write, and error-prone to process. Instead, we put things that ought to be in `
` blocks, like the learning -objectives and challenge exercises, in blocks indented with `>`, and -do a bit of post-processing to attach the right CSS classes to these -blocks. +objectives and challenge exercises, in blockquotes indented with `>`, +and do a bit of post-processing to attach the right CSS classes to +these blocks. diff --git a/FAQ.md b/FAQ.md index 9c1328402ad4af0a54d4df38281ac6ea6f0c86bd..c8639f55829f34f21c2ad90f3cf63cafe968921a 100644 --- a/FAQ.md +++ b/FAQ.md @@ -2,7 +2,7 @@ * *Where can I get help?* - Mail us at [admin@software-carpentry.org](mailto:admin@software-carpentry.org), + Mail [admin@software-carpentry.org](mailto:admin@software-carpentry.org), or join our [discussion list](http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org) and ask for help there. @@ -21,6 +21,7 @@ Because it supports a richer dialect of Markdown than Jekyll (the converter that GitHub uses by default). + In particular, Pandoc can do tables and allows us to add styles to headings. * *What do the [labels](https://github.com/swcarpentry/lesson-template/issues?q=is%3Aopen+is%3Aissue) mean?* diff --git a/LAYOUT.md b/LAYOUT.md index 5b87c14a9bfe0281f0f80c46189bad48bcd0a496..b3353bafd55df076f3781bbb7c3151a9b6cec902 100644 --- a/LAYOUT.md +++ b/LAYOUT.md @@ -7,15 +7,17 @@ submodules or clever tricks with symbolic links). 1. `README.md`: initially a copy of this file. It should be overwritten with short description of the lesson. -2. `pages/`: a sub-directory containing the source of the lesson's - website. See "Pages" below. +2. Other files in the root directory: the source of the lesson's + web pages (and possibly also things like IPython Notebooks and + R Markdown files that those pages are generated from). 3. `code/`, `data/`, and `fig/`: sub-directories containing sample code, data files, and figures. See "Code, Data, and Figures" below. -4. `css/`, `img/`, and `js/`: style sheets, artwork, and Javascript - used in the lesson's web site. See "Support Files" below. +4. `css/`, `img/`, `js/`, and `deck.js/`: style sheets, artwork, and + Javascript used in the lesson's web site. See "Support Files" + below. 5. `_layouts/` and `_includes/`: page templates and inclusions. See "Support Files" below. @@ -40,17 +42,22 @@ plots, and diagrams used in the lessons must go in a `fig/` directory. data file (since the program's working directory will be the root directory, not the `data` directory). -2. We strongly prefer SVG for line drawings, since they are smaller, +2. IPython Notebooks and R Markdown files, which are both code and + the source for web pages, should go in the root directory. + +3. We strongly prefer SVG for line drawings, since they are smaller, scale better, and are easier to edit. Screenshots and other raster images must be PNG or JPEG format. # Support Files Files used to display the lesson, such as artwork, CSS, and -Javascript, are stored in directories of their own. We keep website -artwork separate from graphics used in the lesson's to make it simple -to update the former automatically. Most authors should not need to -modify any of the support files themselves. +Javascript, are stored in `img/`, `css/`, and `js/` directories of +their own, while the `deck.js/` directory contains files used to make +HTML slideshows. We keep website artwork in the `img/` directory +separate from figures used in the lesson (which are stored in `fig/`) +to make it simple to update the former automatically. Most authors +should not need to modify any of the support files themselves. The `_layouts/` directory holds the page templates used to translate Markdown to HTML, while the `_includes/` directory holds snippets of @@ -68,8 +75,7 @@ lessons: # Pages -The `pages/` directory holds the content of the lesson, and must -contain: +The root directory holds the content of the lesson, and must contain: 1. `Makefile`: contains commands to check, preview, and update the repository. Authors should not need to modify this file. @@ -99,9 +105,9 @@ contain: Note that the lesson's title is repeated in several files. We could put this in the Makefile, and insert it into pages when compiling, but -then authors would have to edit the Makefile (which we're trying to -avoid requiring). We could also put it in some sort of configuration -file, but again, we're trying to avoid those. +then authors would have to edit the Makefile (which we want to avoid). +We could also put it in some sort of configuration file, but again, +we're trying to avoid those. ## Home Page @@ -151,7 +157,7 @@ Each topic page must be structured as follows: subtitle: Topic Title minutes: 10 --- - > ## Learning Objectives {.objectives} + > ## Learning Objectives > > * Learning objective 1 > * Learning objective 2 @@ -204,6 +210,8 @@ Each topic page must be structured as follows: objective. 4. Definitions of terms are marked in **bold** (like `**this**`). + Nothing else should be marked as bold text --- use *italics* for + for all other emphasis. ## Motivational Slides diff --git a/pages/LICENSE.md b/LICENSE.md similarity index 100% rename from pages/LICENSE.md rename to LICENSE.md diff --git a/Makefile b/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..f1610019042cbb2b5db4b4c241c9c463d805cb57 --- /dev/null +++ b/Makefile @@ -0,0 +1,47 @@ +# Files. +SRC_PAGES = $(wildcard *.md) +DST_PAGES = $(patsubst %.md,%.html,$(SRC_PAGES)) + +# Inclusions. +INCLUDES = \ + -Vheader="$$(cat _includes/header.html)" \ + -Vbanner="$$(cat _includes/banner.html)" \ + -Vfooter="$$(cat _includes/footer.html)" \ + -Vjavascript="$$(cat _includes/javascript.html)" + +# Default action is to show what commands are available. +all : commands + +## preview : Build website locally for checking. +preview : $(DST_PAGES) + +# Pattern for slides (different parameters and template). +motivation.html : motivation.md _layouts/slides.html + pandoc -s -t html \ + --template=_layouts/slides \ + -o $@ $< + +# Pattern to build a generic page. +%.html : %.md _layouts/page.html + pandoc -s -t html \ + --template=_layouts/page \ + --filter=tools/blockquote2div.py \ + $(INCLUDES) \ + -o $@ $< + +## commands : Display available commands. +commands : Makefile + @sed -n 's/^##//p' $< + +## settings : Show variables and settings. +settings : + @echo 'SRC_PAGES:' $(SRC_PAGES) + @echo 'DST_PAGES:' $(DST_PAGES) + +## clean : Clean up temporary and intermediate files. +clean : + @rm -rf $$(find . -name '*~' -print) + +# very-clean : Remove generated HTML. +very-clean : + @rm -f $(DST_PAGES) diff --git a/README.md b/README.md index bc178cb7743a86d4df06cce1d33efb892d3adf2b..99e7f8cf5f6e2b50263ff3a7e4767aafaff23ed1 100644 --- a/README.md +++ b/README.md @@ -38,24 +38,21 @@ lesson is `data-cleanup`. 6. Build the HTML pages for your lesson: ~~~ - $ cd data-cleanup/pages # or just 'cd pages' if you are already in data-cleanup $ make preview ~~~ - Note that this step requires you to have installed Pandoc - (described below). Note also that it is *not* optional: you - *must* build the web pages for your lesson yourself and push - them to GitHub, rather than relying on GitHub to build them - for you. + This step requires you to have installed Pandoc (described below). + It is *not* optional: you *must* build the web pages for your + lesson yourself and push them to GitHub, rather than relying on + GitHub to build them for you. 7. Commit your changes *and the HTML pages in the root directory of your lesson repository* and push to the `gh-pages` branch of your repository: ~~~ - $ cd data-cleanup # or 'cd ..' if you are in the 'pages' directory - $ git add pages/changed-files.md - $ git add *.html + $ cd data-cleanup + $ git add changed-files.md *.html $ git commit -m "Explanatory message" $ git push origin gh-pages ~~~ @@ -83,8 +80,8 @@ the `gh-pages` branch of their lesson website. To do this: pip install pandocfilters ~~~ -3. To convert Markdown pages in the `pages` directory into HTML pages - in the root directory, go into the `pages` directory and run: +3. To convert Markdown files into HTML pages in the root directory, go + into the root directory of your lesson and run: ~~~ $ make preview diff --git a/pages/discussion.md b/discussion.md similarity index 100% rename from pages/discussion.md rename to discussion.md diff --git a/pages/index.md b/index.md similarity index 100% rename from pages/index.md rename to index.md diff --git a/pages/instructors.md b/instructors.md similarity index 100% rename from pages/instructors.md rename to instructors.md diff --git a/pages/motivation.md b/motivation.md similarity index 100% rename from pages/motivation.md rename to motivation.md diff --git a/pages/Makefile b/pages/Makefile deleted file mode 100644 index 8939a6497b407a26a9fc49d872b7ec4ff09fd601..0000000000000000000000000000000000000000 --- a/pages/Makefile +++ /dev/null @@ -1,58 +0,0 @@ -# Directories. -SRC_DIR = . -DST_DIR = .. - -# Files. -SRC_PAGES = $(wildcard *.md) -DST_PAGES = $(patsubst %.md,$(DST_DIR)/%.html,$(SRC_PAGES)) - -# Inclusions. -INCLUDES = \ - -Vheader="$$(cat ../_includes/header.html)" \ - -Vbanner="$$(cat ../_includes/banner.html)" \ - -Vfooter="$$(cat ../_includes/footer.html)" \ - -Vjavascript="$$(cat ../_includes/javascript.html)" - -# Default action is to show what commands are available. -all : commands - -## preview : Build website locally for checking. -preview : $(DST_PAGES) - -# Pattern for slides (different parameters and template). -$(DST_DIR)/motivation.html : $(SRC_DIR)/motivation.md ../_layouts/slides.html - pandoc -s -t html \ - --template=../_layouts/slides \ - -o $@ $< - -# Pattern to build a generic page. -$(DST_DIR)/%.html : $(SRC_DIR)/%.md ../_layouts/page.html - pandoc -s -t html \ - --template=../_layouts/page \ - --filter=../tools/blockquote2div.py \ - $(INCLUDES) \ - -o $@ $< - -## commands : Display available commands. -commands : Makefile - @sed -n 's/^##//p' $< - -## update : Update the shared files from the GitHub repo holding them. -# FIXME: need to create that repo. -update : - git pull --rebase=false https://github.com/swcarpentry/lesson-template-shared.git master - -## settings : Show variables and settings. -settings : - @echo 'SRC_DIR:' $(SRC_DIR) - @echo 'DST_DIR:' $(DST_DIR) - @echo 'SRC_PAGES:' $(SRC_PAGES) - @echo 'DST_PAGES:' $(DST_PAGES) - -## clean : Clean up temporary and intermediate files. -clean : - @rm -rf $$(find .. -name '*~' -print) - -# very-clean : Remove generated HTML. -very-clean : - @rm -f $(DST_PAGES) diff --git a/pages/reference.md b/reference.md similarity index 100% rename from pages/reference.md rename to reference.md