Add info about Markdown and perhaps a demo of its use?

[weaverbel]

When we talk about plain text formats, I suggest we introduce Markdown. We can point to Markdown being the tool that builds Library Carpentry lessons while still being a plain text format.

I often create (or open) a small Markdown doc on the fly where I format a bulleted list, a numbered list, add an image, add a Web link, and make some text bold and italic and show three sizes of headings. Then I run the file through pandoc and output that single file as a PDF, a Web page and also open it as a formatted Word document. This generally gets people excited about one file, many purposes. What do people think? Too much?

[ccronje]

@weaverbel this would fit well into https://librarycarpentry.github.io/lc-data-intro/03-foundations/index.html, under 'Use machine readable plain text notation for formatting' and 'Applications for writing and reading plain text files' - these sections touch on Markdown and Pandoc.

I think your approach of an 'instructor demo' is probably the best way to go as pandoc is a command line tool, but both demos would help as stepping stones to the Git/GitHub and Unix Shell lessons. Do you have a set of instructions we could add? Do you think we should add it to the Instructor Notes or as an Exercise in the episode itself for learners to explore?

How long does the demo take?

[jt14den]

@ccronje @weaverbel I pulled together an episode on markdown for teaching with LC http://www.tim-dennis.com/2018-libcarp/04-free-text-markdown/ last year. I used in South Africa and it worked pretty well. I had learners use the hackmd.io service in first two exercises b/c you can create md notes as a guest and download as md, odf or html. The last exercise has them making a blog in github - I got this from @weaverbel when she visited UCLA. The top part of the lesson comes from: https://datacarpentry.org/rr-literate-programming/02-literate-programming/index.html. I'd be happy to submit PRs on parts or help find spots to use if you all think it would be useful.

[weaverbel]

I usually create a text file on the fly in a plain text editor that shows different sized headings, a bulleted list, a numbered list, a web link and an image, plus some italic and bold text. Then I push it through pandoc and open the file as a PDF, a web page, and as a formatted Word doc. That usually does the trick. Wow factor.

They can see this fairly plain thing be transformed which is good but they also catch on they can use this to version control writings or drafts of library guides or instructions and then just open files in Word or output to PDF when they are ready to share or publish. Good workflow for people writing scientific papers or theses too.

Belinda Weaver Community and Communications Lead The Carpentries e: bweaver@carpentries.org | p: +61 408 841 882 | t: @cloudaus

On Sun, Jul 15, 2018 at 7:43 AM, Tim Dennis notifications@github.com wrote:

@ccronje https://github.com/ccronje @weaverbel https://github.com/weaverbel I pulled together an episode on markdown for teach LC http://www.tim-dennis.com/2018-libcarp/04-free-text-markdown/ last year. I used in South Africa and it worked pretty well. I had learners use the hackmd.io service in first two exercises b/c you can create md notes as a guest and download as md, odf or html. The last exercise has them making a blog in github - I got this from @weaverbel https://github.com/weaverbel when she visited UCLA. The top part of the lesson comes from: https://datacarpentry.org/rr-literate-programming/02- literate-programming/index.html. I'd be happy to submit PRs on parts or help find spots to use if you all think it would be useful.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/LibraryCarpentry/lc-data-intro/issues/51#issuecomment-405051783, or mute the thread https://github.com/notifications/unsubscribe-auth/ACp3mKWIFagTOYFWpgBa8bRS9UX0pCKAks5uGmXtgaJpZM4VB2-E .

[ccronje]

@jt14den the Markdown section (up to YAML) in http://www.tim-dennis.com/2018-libcarp/04-free-text-markdown/ looks good. This plus @weaverbel's pandoc demo would probably take around 15-20 minutes. What do you think about creating a Markdown episode after Foundations?

[weaverbel]

+1 to that idea ! Shall I try it out in Johannesburg in early September? regards Belinda

Belinda Weaver Community and Communications Lead The Carpentries e: bweaver@carpentries.org | p: +61 408 841 882 | t: @cloudaus

On Thu, Aug 23, 2018 at 2:32 PM, carmi cronje notifications@github.com wrote:

@jt14den https://github.com/jt14den the Markdown section (up to YAML) in http://www.tim-dennis.com/2018-libcarp/04-free-text-markdown/ looks good. This plus @weaverbel https://github.com/weaverbel's pandoc demo would probably take around 15-20 minutes. What do you think about creating a Markdown episode after Foundations?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/LibraryCarpentry/lc-data-intro/issues/51#issuecomment-415286987, or mute the thread https://github.com/notifications/unsubscribe-auth/ACp3mHZWEhadTSYnPKM83PqJeRt_zP5Iks5uTjBegaJpZM4VB2-E .

[drjwbaker]

@weaverbel Did you try it? If so, is there an action here?

[katrinleinweber]

Maybe we should not talk about it too much, but give learners an interactive tutorial like https://commonmark.org/help/. Do you know other such tools?

[libcce]

@pitviper6 and I have combined the regex lesson with an intro to Markdown. We've used hackmd.io and had a brief exercise on popular Markdown. We've also used the Carpentries Code of Conduct (which has Markdown and HTML as an example of something to be fixed with regex). We've used regxr.com as helpful tool for interactively working with regex and content like the CoC. Working with the CoC also highlights again the importance of the CoC.

[ccronje]

Moving forward, @libcce recommends creating a brief episode on Markdown but not reinventing the wheel i.e focus on why this might be important to librarians.

To summarise above:

• @jt14den recommends https://datacarpentry.org/rr-literate-programming/02-literate-programming/index.html
• @katrinleinweber points to https://commonmark.org/help/
• @weaverbel recommends running Markdown through Pandoc to output various formats, demonstrating its flexibility (see Programming Historian lessons https://programminghistorian.org/en/lessons/getting-started-with-markdown and https://programminghistorian.org/en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown)
• @libcce points to hackmd.io and using the Carpentries Code of Conduct to learn Markdown (see https://pad.carpentries.org/2018-10-18-Lib-Carp-UNC)

There may be draw drawbacks to Markdown which would need to be considered also i.e. pros/cons.

[drjwbaker]

This is a small section on markdown in https://librarycarpentry.org/lc-data-intro/03-foundations/index.html on the value of machine readable plain text notation. Again, I think this just needs a prod in the right direction for further reading, plus - perhaps - an example of markdown.

[sharilaster]

@sharilaster to reframe as a fresh issue for #mozsprint

[sharilaster]

Opened #103 as a fresh issue to tag for #mozsprint and #good first issue. Thank you to all contributors for the suggestions!