diff --git a/_episodes/04-formatting.md b/_episodes/04-formatting.md index bf131a72..6cbeb907 100644 --- 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 +> +> +> Hello World +> +> +> ``` +> ```` +> +> ```html +> +> +> Hello World +> +> +> ``` +> +> 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 index 3b7949f8..a159415e 100644 --- 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} -An example figure plotting carat of diamonds against their price, with the colour of the data points based on the cut of the diamond. +An example figure plotting carat of diamonds against their price, with the colour of the data points based on the cut of the diamond. 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 index ec9b4b44..dc85afc4 100644 Binary files a/fig/rmd-05-plot-example-1.png and b/fig/rmd-05-plot-example-1.png differ diff --git a/index.md b/index.md index 198a58a3..979825f9 100644 --- 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: +> - R Markdown Lesson Template Generator: +> - Lesson Maintainer/Author Documentation: +> - Transition Guide: +> - General Information: +> - Discussion: +> - Bug Reports: +> - Contact: zkamvar at carpentries dot org +{: .callout} + + For guidelines on how to develop curriculum content, please visit [The Carpentries Curriculum Development Handbook][curriculum-handbook].