update formatting chapter about code blocks (9481b4a1) · Commits · NDIP / Nova Packages / Nova Carpentry Tutorial

_episodes/04-formatting.md

+46 −1

Original line number	Diff line number	Diff line
		@@ -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.

_episodes/05-rmarkdown-example.md

+2 −2

Original line number	Diff line number	Diff line
		@@ -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.

fig/rmd-05-plot-example-1.png

−128 KiB (407 KiB)

Loading image diff...

index.md

+1 −0

Original line number	Diff line number	Diff line
		@@ -27,6 +27,7 @@ permalink: index.html # Is the only page that doesn't follow the pattern /:path
		> - 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