Update README.md

README.md

@@ -49,6 +49,88 @@ complete the initial configuration of a new lesson repository built from this te
    - the life cycle of the lesson (e.g. `pre-alpha`)
    - the human language the lesson is written in (e.g. `deutsch`)
 
+## Notes for CMS Open Data lessons
+
+No attempt for a local build was made, and in principle, there is no need to install R or Pandoc. Note, however, that the content should be in [Pandoc-flavored Markdown](https://pandoc.org/MANUAL.html). If one wishes to test locally, the instructions are provided in [The Carpentries Workbench][workbench] documentation.
+
+The setup instructions are in `learners/setup.md` and the separate pages under `episodes`.
+
+The `md-outputs` branch shows after setting up the repository. No need to merge them.
+
+The schedule shows only in the "Instructor view": https://cms-opendata-workshop.github.io/workshopqcd-2024-lesson-docker/instructor/index.html 
+Use this link if you want to show it.
+
+### Updating an old lesson to the new template
+
+There might be a tool somewhere, but if doing it by hand:
+
+1. Change questions (note the empty line after items), objectives and keypoints to
+   ```
+   :::::: questions
+   - question 1
+   - question 2
+
+   ::::::
+
+   :::::: objectives
+   - objective 1
+   - objective 2
+
+   ::::::
+
+   <!-- EPISODE CONTENT HERE -->
+
+   :::::: keypoints
+   - keypoint 1
+   - keypoint 2
+   ::::::
+   ```
+2. Remove the double quotes of the question, objectives and keypoints.
+3. Make sure that keypoints are at the end of the text.
+4. Find all `{: .callout}`, `{: .challenge}`, `{: .testimonial}` etc tags and and remove the preceeding `> ` for the block and change them to
+
+   ```
+   ::: callout
+   This is a callout block. It contains at least three colons
+   :::
+   ```
+   or
+
+   ```
+   ::::::::::::::::::::::::::::::::::::: challenge
+
+   ## Question
+
+   Q: question
+
+   :::::::::::::::: solution
+
+   A: answer
+
+   :::::::::::::::::::::::::
+   :::::::::::::::::::::::::::::::::::::::::::::::
+   ```
+
+### Documentation
+
+See e.g.
+
+- https://carpentries.github.io/lesson-development-training/
+- https://carpentries.github.io/sandpaper-docs/index.html
+
+### Indents and unexpected code blocks
+
+Note that double-indent (two tabs) or anything more that three spaces produces a code block. That's not necessarily what one would expect.
+Also, in some special cases, in nested lists, the second level items might appear as a code block.
+
+### Figures
+
+Figures should be located under `episodes/fig`, and included, for example, with
+
+```
+![](fig/portal_screenshot_landing_page.png)
+```
+
 
 [cff-home]: https://citation-file-format.github.io/
 [cff-sandpaper-docs]:  https://carpentries.github.io/sandpaper-docs/editing.html#making-your-lesson-citable