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.