Merge pull request #387 from carpentries/workbench-announcement

Add workbench announcement; fix points of confusion
carpentries · Jan 9, 2023 · b92de36 · b92de36
2 parents 2c19dff + f0a2238
commit b92de36
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 54 deletions.
diff --git a/_episodes/04-formatting.md b/_episodes/04-formatting.md
@@ -122,7 +122,7 @@ Authors should *not* use:
 
 ## Formatting Code
 
-Inline code fragments are formatted using back-quotes.
+Inline code fragments are formatted using backticks (`` ` ``).
 Longer code blocks are formatted by opening and closing the block with `~~~` (three tildes),
 with a class specifier after the block:
 
@@ -162,8 +162,11 @@ The [template]({{ site.template_repo }}) provides three styles for code blocks:
 ~~~
 {: .error}
 
+
+
 ### 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,
@@ -225,6 +228,48 @@ RETURN (0)
 ~~~
 {: .language-sql}
 
+> ## Alternative Syntax highlighting
+> 
+> The majority of our lessons that use styles will have the three tilde syntax, but this is a
+> historical artifact and not commonly used outside of kramdown. You can specify a code block by
+> using three backticks followed by the class instead of the syntax above.
+> 
+> ````markdown
+> ```html
+> <html>
+> <body>
+> <em>Hello World</em>
+> </body>
+> </html>
+> ```
+> ````
+>
+> ```html
+> <html>
+> <body>
+> <em>Hello World</em>
+> </body>
+> </html>
+> ```
+> 
+> NOTE: this syntax will _not_ work for error, output, or warning code blocks.
+>
+> ### Historical Artifacts
+>
+> This code block syntax with three tildes followed by an 
+> [inline attribute list](https://kramdown.gettalong.org/syntax.html#inline-attribute-lists)
+> is [a departure from the original markdown
+> syntax](https://kramdown.gettalong.org/syntax.html#fenced-code-blocks). You may be wondering why
+> Carpentries lessons used this syntax in the first place if it was so different from original
+> markdown.
+>
+> At the time this guide was originally written, Lessons in The Carpentries were
+> using Jekyll with [kramdown](https://kramdown.gettalong.org/) to render
+> Markdown to HTML and back then, kramdown did not recognise three backticks as
+> code blocks. 
+{: .callout}
+
+
 > ## Highlighting for other languages
 > You may use other `language-*` classes to activate syntax highlighting
 > for other languages.
@@ -439,56 +484,5 @@ You can add a drop shadow effect to images by applying the
 
 [jekyll-link-tag]: https://jekyllrb.com/docs/liquid/tags/#link
 
-## Adding Formatted Equations
-
-The template supports rendering of equations via [KaTeX](https://katex.org/).
-This option must be activated by adding `math: true` to the `_config.yml` file 
-or YAML front matter of the Markdown file where you wish to use it.
-
-Mathematical expressions can then be added to the page content using the LaTeX syntax.
-
-Expressions can be written inline:
-
-~~~
-{% raw %}Inline expressions can be added between `$` symbols, e.g. $E = Mc^2$.{% endraw %}
-~~~
-{: .source}
-
-with the result:
-
-Inline expressions can be added between `$` symbols, e.g. $E = mc^2$.
-
-Or as a block across multiple lines:
-
-~~~
-{% raw %}$$
-    \lim_{x \rightarrow 0}
-    \frac{
-        \sin x
-    } {
-        x
-    }
-    = 1
-$${% endraw %}
-~~~
-{: .source}
-
-with the result:
-
-$$
-    \lim_{x \rightarrow 0}
-    \frac{
-        \sin x
-    } {
-        x
-    }
-    = 1
-$$
-
-The example above was taken from the chapter _Typesetting Mathematical Formulae_,
-in [The Not So Short Introduction to LaTeX](https://tobi.oetiker.ch/lshort/lshort.pdf).
-[The Mathematics chapter of the LaTeX WikiBook](https://en.wikibooks.org/wiki/LaTeX/Mathematics)
-is a good reference guide for those wishing to add equations
-and mathematical expressions to their lessons.
 
 {% include links.md %}
diff --git a/_episodes/05-rmarkdown-example.md b/_episodes/05-rmarkdown-example.md
@@ -39,7 +39,7 @@ information.
 ## Structure of a RMarkdown file in the `_episodes_rmd` folder
 
 Our template requires that the YAML header of your RMarkdown file includes the
-`source: Rmd` in addition of the other entries that are expected. For instance, the YAML header for
+`source: Rmd` in addition of the other entries that are expected. For instance, the YAML header for 
 this episode is:
 
 
@@ -160,7 +160,7 @@ ggplot(diamonds, aes(x = carat,  y = price, color = cut)) +
 ~~~
 {: .language-r}
 
-<img src="../fig/rmd-05-plot-example-1.png" title="An example figure plotting carat of diamonds against their price, with the colour of the data points based on the cut of the diamond." alt="An example figure plotting carat of diamonds against their price, with the colour of the data points based on the cut of the diamond." width="612" style="display: block; margin: auto;" />
+<img src="../fig/rmd-05-plot-example-1.png" alt="An example figure plotting carat of diamonds against their price, with the colour of the data points based on the cut of the diamond." width="612" style="display: block; margin: auto;" />
 
 The alternative text for these embedded images will be the same as
 the figure caption specified with the `fig.cap` parameter.

diff --git a/fig/rmd-05-plot-example-1.png b/fig/rmd-05-plot-example-1.png
diff --git a/index.md b/index.md
@@ -6,6 +6,30 @@ permalink: index.html  # Is the only page that doesn't follow the pattern /:path
 
 {% include gh_variables.html %}
 
+> ## New Lesson Infrastructure Coming May 2023
+>
+> Our new lesson infrastructure, [The Carpentries Workbench](https://carpentries.github.io/workbench/)
+> is currently undergoing [beta testing](https://carpentries.github.io/workbench/beta-phase.html)
+> and will become default for official Carpentries lessons in May 2023.
+>
+> This new infrastructure is designed to be more accessible and easier to use than the styles
+> infrastructure by separating tools from the content.
+>
+> **If you would like to create a new lesson, we encourage you to use The Workbench.**
+>
+> ### Resources
+> 
+> - Markdown Lesson Template Generator: <https://bit.ly/new-lesson-md/>
+> - R Markdown Lesson Template Generator: <https://bit.ly/new-lesson-rmd/>
+> - Lesson Maintainer/Author Documentation: <https://carpentries.github.io/sandpaper-docs/>
+> - Transition Guide: <https://carpentries.github.io/workbench/transition-guide.html>
+> - General Information: <https://carpentries.github.io/workbench/>
+> - Discussion: <https://github.com/carpentries/workbench/discussions>
+> - Bug Reports: <https://github.com/carpentries/workbench/issues>
+> - Contact: zkamvar at carpentries dot org
+{: .callout}
+
+
 For guidelines on how to develop curriculum content, please visit
 [The Carpentries Curriculum Development Handbook][curriculum-handbook].