Skip to content

Latest commit

 

History

History
349 lines (232 loc) · 14.2 KB

README.md

File metadata and controls

349 lines (232 loc) · 14.2 KB

Markdown Workshop

This is a practical workshop about the syntax and the use of the Markdown format. In particular, we will focus on the GitHub Flavored Markdown, used by GitHub. See the full specification of the GitHub Flavored Markdown here.

Note

Markdown is not only used in GitHub / GitLab and other software development platforms, but also in chat message engines such as Discord, note taking apps such as HackMD and wiki engines such as MDwiki. Parts of the Markdown syntax are also used on WhatsApp, MS Teams and other chat message engines, particularly for text formatting.

Set Up

To set up the workshop environment, follow the steps:

  1. First of all, fork this repository. Use the Fork button on the top right of the repository page.

  2. Create a local clone of your fork:

    git clone [email protected]:<your-github-username>/workshop-markdown
cd workshop-markdown/

    Make sure you have a public SSH key configured for your GitHub account, in order to clone the repository. Replace the <your-github-username> string above with your username on GitHub.

  3. Add the upstream remote to point to the upstream repository:

    git remote add upstream https://github.com/rosedu/workshop-markdown
git fetch upstream

And let's get going! 🚀

Markdown Use in Public Repositories

Let's start with checking how Markdown is being used in public repositories.

This Repository

First, see this README.md file:

cat README.md

You could also edit it using your preferred editor (Vim, Emacs, Nano, VS Code, Sublime) to also have syntax highlighting.

Also check the README.github.md file, a direct copy of the README.md file in the workshop-github repository. To see the actual contents of a file on GitHub (such as the README.md file in the workshop-github repository), click the Raw button in the top-right corner. You'll get to this page in raw format.

Identify syntax aspects in the documentation for GitHub Flavored Markdown. See:

  • The use of #, ##, ### for section headings.
  • The use of backticks for typewriter font, used for the names of files, functions, and
  • The use - and \* for unordered lists.
  • The use of 1. for ordered lists.
  • The syntax used for links.
  • The use of triple backticks for code snippets.
  • And many others.

See how the Markdown syntax is rendered on GitHub for this README.md file and the README.github.md file.

Operating Systems (from Open Education Hub)

See Markdown files in the Operating Systems (Open Education Hub / cs-pub-ro) repository. For files in the repository, check the raw format. And check how they are rendered on the website.

Unikraft Docs

See Markdown files in the Unikraft Docs repository. For files in the repository, check the raw format. And check how they are rendered on the website

OWASP Website

See Markdown files in the owasp.github.io repository. For files in the repository, check the raw format. And check how they are rendered on the website.

Using the Repository Fork

The upstream repository already has branches numbered cdl-00 to cdl-99. The instructors will assign each of you a branch.

After the branch is assigned, create a local version of that branch locally:

git branch <assigned-branch> upstream/<assigned-branch>

You will create pull requests to your assigned branch.

This means you will follow the steps:

  1. Create a branch. Make sure you are on that branch.
  2. Make changes.
  3. Create commits.
  4. Push changes to your fork.
  5. Create a pull request from that push. The pull request must be target to your assigned branch (not the main branch).

Fix a Markdown File

The dynamic-linking.ro.md Markdown file has errors in it. Fix these errors as part of a pull request.

Follow the instructions above to create the pull request. Make sure you have good commit messages and a good pull request description.

Target the pull request to your assigned branch.

Ask the instructors to review your pull request. Make updates as required. Have your pull request approved and merged on top of your assigned branch.

Check the GitHub web view of the upstream repository for your assigned branch. Click on the button with main (the branch button) and select your branch.

Check the contents of the dynamic-linking.ro.md file and see if it is now rendered correctly.

Clean Up After Pull Request

After the pull request is merged, clean up your work environment. That is:

  1. Go the pull request GitHub view and delete the remote branch.

  2. Remove the reference to the remove branch in your clone:

    git remote prune origin

  3. Checkout the main branch:

    git checkout main

  4. Remove the local branch that you used for creating the pull request. It has the same name as the one you remote branch you removed above:

git branch -D <work-branch-used-for-PR>

  1. Fetch the updates for your assigned branch. Your assigned branch is now updated after the pull request was merged:

    git fetch upstream
git checkout <your-assigned-branch>
git rebase upstream/<your-assigned-branch>

  2. Check the branch:

    git log

Create a Markdown File

The helloworld-print.pdf file is a PDF print of a GitHub view of a Markdown file. Create the helloworld.md file that will generate that precise GitHub view.

Note

The first large "Hello, World!" message is an image file: the file helloworld.png in the repository.

Make sure you do the following:

  1. Start by creating a branch where you do your work. Use helloworld for the branch name:

    git checkoout -b helloworld

    This will be the branch from where you will create a pull request. As usual, the future pull request will target your assigned branch in the upstream repository.

  2. Copy-paste contents from the PDF file. Open the helloworld-print.pdf file in a PDF viewer, select text, copy in the helloworld.md file.

  3. Use correct syntax items for typewriter format, links to sections, code snippet format, tables. See the GitHub Markdown spec.

  4. Create and or update commits. Do periodic (force) pushes of the work branch:

    git push --force origin <work-branch>

    After each push, check the GitHub view of the work branch in your fork of the GitHub repository.

    Check the contents of the helloworld.md file on your GitHub fork and see if it is now rendered correctly.

  5. After completing the task, submit the helloworld.md Markdown file as part of a pull request.

    Follow the instructions above to create the pull request. Make sure you have good commit messages and a good pull request description.

    Target the pull request to your assigned branch.

  6. Ask the instructors to review your pull request. Make updates as required. Have your pull request approved and merged on top of your assigned branch.

Clean Up After Pull Request

After the pull request is merged, go to the same steps as above to clean your pull request.

Your Turn

Add a Markdown file with contents of your own. Use as many Markdown syntax features as possible.

Be sure to have at least:

  • a link
  • a code snippet
  • a table
  • an ordered list
  • an unordered list
  • headings
  • an image
  • an emoticon / emoji

Submit the Markdown file as part of a pull request.

Follow the instructions above to create the pull request. Make sure you have good commit messages and a good pull request description.

Target the pull request to your assigned branch.

Ask the instructors to review your pull request. Make updates as required. Have your pull request approved and merged on top of your assigned branch.

Check the GitHub web view of the upstream repository for your assigned branch.

Clean Up After Pull Request

After the pull request is merged, go to the same steps as above to clean your pull request.

GitHub Profile Page

GitHub provides you to option to have a GitHub profile page, that you can use as a form of open source CV / portfolio. You can check the profile pages below as examples:

The profile pages are rendered from a standard repository named exactly as the account name. We will call this repository the profile repository. See the contents of each account repository for the above accounts:

The repository consists of a single README.md Markdown file. This README.md file in the profile repository is automatically rendered by GitHub on the account profile page.

Check the raw contents of README.md files above to see how the profile page is created.

Create Your Own GitHub Profile Page

Create your own GitHub profile page. Follow the steps:

  1. Create your GitHub profile repository named exactly as your account name. Initialize it with a simple README.md file as instructed in the repository creation screen.

  2. See the initial output of the repository on your GitHub page.

  3. Clone the profile repository locally:

    git clone [email protected]:<your-github-username>/<your-github-username>
cd <your-github-username>

    Replace the <your-github-username> string above with your username on GitHub.

  4. Update the README.md file in the repository with the contents you want for your profile. Take inspiration from the GitHub profile pages above.

  5. Create commits with the updates to the README.md file. Push commits to the GitHub remote repository. Now check your resulting profile page on your GitHub page.

Create a Website with GitHub and Markdown

We can use the contents of a GitHub repository, written with Markdown, to create a website. This feature is called GitHub Pages.

This is, for example, how the Hardware-Software Interface website is constructed, from the corresponding cs-pub-ro/hardware-software-interface repository. And the Operating Systems website also from the corresponding cs-pub-ro/operating-systems repository.

The content of this repository is published at: https://rosedu.github.io/workshop-markdown/ The main page of the website (https://rosedu.github.io/workshop-markdown/) is a rendering of README.md.

There are also renderings of the other pages:

To render these Markdown files as a website using GitHub Pages, we followed the instructions here. The image below presents the configuration we did to configure GitHub Pages.

GitHub Pages Settings

Do It for Your Fork

Do the same configuration as above for your repository fork, at https://github.com/<your-github-username>/workshop-markdown. Replace the <your-github-username> string above with your username on GitHub.

When configuring the repository in the Settings screen, the Pages option on your GitHub repository interface, use your own branch cdl-.. as the publishing source.

If all is done correctly, you will be able to see the Markdown files rendered:

  • README.md will be rendered at https://<your-github-username>.github.io/workshop-markdown/
  • README.github.md will be rendered at https://<your-github-username>.github.io/workshop-markdown/README.github.html
  • dynamic-linking.ro.md is rendered at https://<your-github-username>.github.io/workshop-markdown/dynamic-linking.ro.html
  • dynamic-linking.ro.md is rendered at https://<your-github-username>.github.io/workshop-markdown/helloworld.html

Create a Website from a Repository

Create a new separate repository on GitHub and create a website from it, adding content in Markdown. Name it as you want and use content (in Markdown) as you want. Make it personal, make it fun, use your imagination.

We recommend you use the docs/ directory in the repository to store the website content. Outside docs/ you will have content not rendered.

Then configure the repository to be rendered using GitHub Pages. See its contents at https://<your-github-username>.github.io/<repository-name>/.