tcaarsbl17

Getting Started with Markdown and Git

1. Preliminary Setup

   • Created a repository on Github
   • Added a docs directory with an index.md file
   • Turned on GitHub Pages and configured theme in settings
2. Create a GitHub account
3. Accept invite as contributor to repository

4. Edit a file and commit changes

   • See Mastering Markdown for the basics on using GitHub Flavored Markdown (GFM).
   • For a fuller explication of the GFM standard, see GitHub Flavored Markdown Spec.
   • Markdown can be used in the .md file we are working on together and in the commit message.
   • There are many git workflows that teams can use, here is a simple introduction that gives the basics of the git process.

5. Add a new file to the repository.

   • browse to docs directory of repository
   • create file with .md extension
   • add necessary front matter (see example in another file, e.g. layout and title)

6. Add an issue that the team needs to discuss about the project.

   • notice all of the options you have with assigning issues or categorizing, etc.
   • you can use markdown in your issue too :)

7. Choose an editor (e.g. Atom)

   • Install Atom
   • Setup Atom for Github
   • Learn the git workflow in Atom (team decide on branching or not, etc.)
   • commit and push changes to shared repository

8. Use pandoc to convert markdown to word

   • Mac OS: install Homebrew package manager
   • Install pandoc (Use homebrew for Mac OS)

   • use command something like

       pandoc -o [output_docx] -f markdown -t docx [input_md] --smart
     

9. How to use VIM
   • Here is the Linux Tutorial
10. A helpful walk-through on writing with Markdown and Pandoc: Sustainable Authorship in Plain Text using Pandoc and Markdown