Markdown and GitHub

First Steps Toward learning Modern Digital Practices for Sustainable and Shareable Research.

Markdown and GitHub

Tuesday January 26, 2018, 12:30-3:30pm PST
UCSB South Hall 2509

Slideshow Links Repository Sandbox Workshop Video

The Mellon Foundation funded WhatEvery1Says project at UCSB (WE1S) will be holding the first in its series of workshops on “Markdown and Github: First Steps Toward learning Modern Digital Practices for Sustainable and Shareable Research.”

  • Markdown is a plain text format for writing structured documents. First developed in 2004, Markdown is gaining in popularity because it is easy to write and read, as well as to create consistent formatting that can be rendered in a wide variety of formats and environments, including GitHub.
  • GitHub is a Web-based document and code repository hosting service that provides extensive version control functions and features designed for collaboration. Widely used for computer code, GitHub is becoming increasingly popular with humanities scholars needing these features, and even for hosting blogs and websites.

Across the disciplines, including in the social sciences and humanities, researchers are using these tools to create research environments that enable the maintenance of stable, easy-to-migrate documents, the clear versioning of their work, and the ability to contribute to and draw from shared-project resources.

Scott Kleinman, one of the WE1S project's PIs, will lead the workshop. A professor of English at California State University, Northridge, Kleinman is also project lead for the Lexomics project, which produces the online text-analysis tool Lexos.

The workshop is geared for beginners, including students and faculty. It will also serve the purpose of helping to train some of WE1S's research assistants in methods used by the project.

Markdown-mark logo by Dustin Curtis, Creative Commons Zero v1.0 Universal. GitHub Octocat logo used as permitted by GitHub.

Markdown References

Online Markdown Tools

Markdown Extensions

  • markdownlint GitHub repo (Extension for Visual Studio Code)
  • vscode-markdown-pdf GitHub repo (Extension to convert Markdown to PDF in Visual Studio Code)

    Hints:

    • Follow the instructions for modifying the settings on the GitHub repo to change the `markdown-pdf.format` setting from "A4" to "Letter". This will improve the placement of page breaks.
    • If you still find that page breaks are not inserted where you want them, you can force a page break at a specific location by inserting <div style="page-break-after: always;"></div> (with a line break before and after) in your Markdown document.

Tools That Use Markdown

  • Ryver (Team Communication)
  • Jekyll (Static Website Generator)

GitHub References and Tutorials

JSON Tools

Data Package References