Markdown and GitHub
https://joemull.net/slides/markdown-and-github.html
These slides were created by Joe Muller and are under copyright by Birkbeck, University of London. They can be re-used with attribution under CC BY 4.0.
Why do computers need markup?
Input
Jury acquits attorney of tax fraud charges Oliver Laughland and Ramon Antonio Vargas in New Orleans Thu 28 Jul 2022 18.12 EDT New Orleans’s district attorney, Jason Williams, has been acquitted of all charges... Williams, along with his private practice law partner Nicole Burdett, faced a 10-count federal indictment...
Output
Spaces and symbols express the structure
Input
# Jury acquits attorney of tax fraud charges
_Oliver Laughland and Ramon Antonio Vargas in New Orleans_
**Thu 28 Jul 2022** 18.12 EDT
New Orleans’s district attorney, Jason Williams, has been acquitted of all charges...
Williams, along with his private practice law partner Nicole Burdett, faced a 10-count federal indictment...
Output
What kind of markup is best? (Coombs 1987, 936)
“Presentational markup is designed for reading. Procedural markup is designed for formatting, but usually only by a single program. Descriptive markup is moderately well suited for reading, but primarily designed to support an open class of applications (e.g., information retrieval).”
Descriptive markup advantages
Coombs and his coauthors identified four advantages of descriptive markup (1987, 946):
- Simpler authoring process because focus is just on content
- Declarative over procedural programming
- Separation of form and content
- Easier maintenance over time
- Abstraction of typesetting behavior away from authoring context
- More portability once standardised
- The World Wide Web would be created in another 10 years
- Semantic and pragmatic information allow for alternative views
- Semantic markup is the foundation of accessible web content
Watch: What is Markdown?
Live coding: Examples of Markdown
You can experiment with Markdown using any environment that supports it as an authoring format.
Some examples:
- Garen Torikian, Markdown Tutorial
- The README.md file for the Web Development repository on GitHub
- Your code editor, if you already use one, with a markdown plugin or extension
Watch: What is GitHub?
GitHub repository examples
GitHub repositories can be anything from major commercial software projects to small personal experiments.
| Repository | Description |
|---|---|
| vuejs/core | a large free and open source (FOSS) JavaScript framework |
| openlibhums/janeway | a FOSS web application with a handful of developers, including Joe |
| openlibhums/memory-alpha | a user support website under construction, currently private |
| avauga03/DietRight | a student website with a nutrition theme |
Things to notice on a GitHub repository
- The owner (can be a person or organization)
- The code file structure
- The README file
- Documentation of current development in issues and pull requests
- Ability to view any code file and see who wrote each line, and when
- Number, frequency, and date of commits and releases
- Public vs. private visibility, open source licenses
- Number of contributors
- Number of forks and stars
- Breakdown of languages
"In our study, we investigated to what extent the GitHub interface embedded inclusivity bugs and how these inclusivity bugs impacted users’ performance with different cognitive styles (i.e., Abis and Tims)... Participants in the Control group felt scared by the GitHub interface; (3) process-oriented learners were hampered by a lack of clear instructions on how to contribute."
References
Codecademy. What Is Markdown? 2019, https://www.youtube.com/watch?v=f49LJV1i-_w.
Code Institute. 2022. What Is GitHub | How to Use It | Benefits of GitHub. https://www.youtube.com/watch?v=BUE2LaSzijM.
Coombs, James H., Allen H. Renear, and Steven J. DeRose. 1987. “Markup Systems and the Future of Scholarly Text Processing.” Communications of the ACM 30 (11): 933–47. https://doi.org/10.1145/32206.32209.
Santos, Italo, João Felipe Pimentel, Igor Wiese, Igor Steinmacher, Anita Sarma, and Marco A. Gerosa. 2023. “Designing for Cognitive Diversity: Improving the GitHub Experience for Newcomers.” 2023 IEEE/ACM 45th International Conference on Software Engineering: Software Engineering in Society (ICSE-SEIS), May, 1–12. https://doi.org/10.1109/ICSE-SEIS58686.2023.00007.
Torikian, Garen. n.d. “Markdown Tutorial.” Accessed October 5, 2025. https://www.markdowntutorial.com/.