Markdown

By the end of this training, participants will:

• select and use a markdown editor that offers real-time preview functionality.
• see how the preview feature aids in visualizing the final output.
• create a simple markdown document (headings, bold, italic).
• develop a complex markdown document
• trouble-shoot common markdown issues
• apply markdown in language technology tools (e.g. Project plan task descriptions, Notion)

1. Introduction to Markdown

• What Markdown is: a simple way of marking up plain text so that it is easy to read and write, yet can be seamlessly converted to structurally valid HTML.
• Where it is used: websites (e.g., the source files for the Paratext Manual), README files, the Paratext Project plan, and many more.
• History & Evolution: It started with two people, and as it has grown, there are several variants. (e.g., GitHub Flavored Markdown).

2. Core Syntax & Features

• Basic Elements: Headers, lists, emphasis (bold/italic), links, and images.
• Advanced Features: Code blocks, tables, blockquotes, and horizontal rules.
• Inline HTML: How and when to use HTML within Markdown for extra customization.

3. Tools & Editors

• Text Editors & IDEs: Overview of popular Markdown editors (Visual Studio Code, Notepad++, Google Docs (imports and exports md), etc.).
• Preview & Conversion Tools: Tools that help visualize Markdown in real-time and convert it (Pandoc, Markdown converters).

4. Practical Applications

• Documentation: Using Markdown for project documentation and technical writing.
• Version Control: How Markdown integrates with Git for documentation, README files, and wikis.
• Content Management Systems: Usage in blogs, static site generators (Jekyll, Hugo), and other publishing tools.

5. Best Practices

• Consistency: Tips for keeping Markdown documents clear and maintainable.
• Collaboration: Strategies for working with teams (e.g., using Markdown in pull requests, collaborative platforms like GitHub).
• Accessibility: Ensuring that Markdown documents are accessible to diverse audiences, including language technology contexts.

6. Customizations and Extensions

• Flavors of Markdown: Differences between standard Markdown and variants (CommonMark, GitHub Flavored Markdown).
• Extensions & Plugins: How to add extra functionalities like footnotes, diagrams, or mathematical expressions.
• Integration with Language Tools: Discuss how Markdown can be used in localization, documentation, or in developing language technology software.

7. Real-World Examples & Demos

• Case Studies: Present examples where Markdown has streamlined documentation or improved workflow.
• Live Demo: A hands-on session converting a document from Markdown to HTML or using a Markdown editor effectively.

8. Interactive Session

• Q&A Session: Address common questions and pitfalls.
• Group Exercise: A quick group task where participants convert or edit a Markdown document.

9. Additional Resources

• Reference Guides: Provide links to cheat sheets and comprehensive guides.
• Community & Support: Highlight forums, communities, or official documentation for ongoing support.