- Learn about GitHub and Markdown
- Create your own Markdown profile page
- Understand the GitHub workflow (including forks, repositories, commits, and pull requests)
GitHub – a web-based hosting service for version control using git, source code management system for OLE.
Markdown – a lightweight markup language with plain text formatting syntax.
MDwiki – a CMS/Wiki built in HTML5/Javascript and runs on the client. It uses Markdown as its input markup language. The OLE support website you are currently viewing is realized with MDwiki.
Example of Markdown syntax on the left side and the way it is rendered to HTML on the right side (click on image to expand):
A Markdown cheat sheet that might help you create your own Markdown page later:
GitHub – Mastering Markdown - The official GitHub Guide for Markdown syntax.
Git Cheat Sheet - A resource for commonly used git commands.
Markdown cheat sheet - A bigger Markdown cheat sheets with examples
Markdown Web Editor - An Online Markdown Web Editor
Markdown Tutorial - An interactive tutorial to learn Markdown.
Markdown Interactive Tutorial - Another awesome interactive tutorial to experiment and learn more Markdown syntax.
NOTE: • If you have not used Markdown before, we recommend you to go through at least one of the tutorials/guides. For more reference or tutorial about Markdown, jump to Useful Links. • Markdown != HTML • If you like to use emoji in your profile, copy the actual emoji directly instead of git markdown markup code or HTML unicode (Use '🐱' instead of ':emojicode:'). You can use this link to copy emoji. • Notice that the task lists feature is not supported by MDwiki, although it is supported by Github. Your task lists may look good on Github preview but will not on MDwiki.
Below is a summary of the steps that we will walk you through:
- Login to GitHub with your username and password
- Find and fork the correct repository
- Go to Settings and rename your repository
- Check if your github.io works
- Create a new file as your personal MDwiki page and commit your changes
- Open a pull request
Since you have already created an account on GitHub, we will assume that you understand the basic layout and functionality. If you don't, please explore and do some basic googling.
There is a lot to learn about GitHub, but to acclimatize you to it, we will walk you through a basic example of how to create your own <username>.github.io and allow you to edit and commit your changes.
NOTE: Existing GitHub users, please make sure to set your email address per local repository or make sure global settings are accurate. Follow this for more information.
Forking is essentially creating a copy of a repository on your own GitHub account, to avoid editing and, possibly, messing up with the main repository.
Now, go to OLE's github.io repository and click on the "Fork" button as shown in the screenshot below to fork the repository to your own GitHub account.
NOTE: It is very important to distinguish between your personal GitHub account and OLE's account. As we want to keep a 'clean' version of our code, you should first fork the repository. You should commit any changes you make to a branch on this version of the repository. These changes should be sent back to OLE's repository through pull requests. OLE's code will be updated when the pull requests are approved.
After you fork the repository, you will be on your repository: <YourUserName>/open-learning-exchange.github.io. Next, you should go to Settings at the top middle of the page and rename your repository to <YourUserName>.github.io. See example below.
Note: In case you have the https://YourUserName.github.io in use, please refer to the FAQ (Q16).
After renaming your forked repository, go to https://YourUserName.github.io and make sure it works.
Don't worry if you see a 404 page not found error. When you access the link, it will take a while for the page to load and run. Make sure in Settings > GitHub Pages, the source is set to master branch.
Again, when you're editing on GitHub, it is important to make sure you are working on your own GitHub repository. To that end, make sure there is your own username before the slash and the correct repository after the slash. For example: EmilyLarkin/EmilyLarkin.github.io.
First, before creating your file, we need to create a new branch
- Click on the branch selector menu (make sure it says "Branch: master", if it's something else, click on it and switch to master branch first
- Give your new branch a short and descriptive name (you can read more about branch naming here)
- Click on "Create branch: your-new-branch-name". Then you should see "Branch: your-new-branch-name" on the branch selector menu
Next, we are going to create your page
- Go to the
pages/vi/profilesfolder - Make sure you are still on the new branch you just created, look for "Branch: new-branch-name" on the branch selector menu
- Click
Create new filebutton - Name the file exactly the same as your GitHub username with file extension
.md
- It is important that you stick with your GitHub username so we could easily identify you
- For reference, an example of a link to a personal page is https://github.com/xyb994/open-learning-exchange.github.io/blob/master/pages/vi/profiles/xyb994.md.
Yours should be named in the same manner, only using your username.
Then, in the new Markdown file, include the following information:
- your name, location/time zone, and OS (including version)
- a short description of yourself (so your fellow virtual interns know who you are)
You may use the "Preview" tab to have a primitive look of what your Markdown will look like. Please use at least 5 different types of Markdown elements so you can get an idea of how it works. Avoid using HTML as the purpose of Markdown is to make pages easy to write and read. Try to be as creative as possible. Some good examples of profiles are: Profile 1 (links), Profile 2 (picture), Profile 3 (lists)
When you are finished, press 'commit changes' below.
If you need to edit your file again, click the pencil icon to edit (as shown below).
Or Another way to edit the file is to, go to File change and edit file (as shown below)
Now, check what this looks like on your own page https://raw.githack.com/YourUserName/YourUserName.github.io/YourBranchName/#!pages/vi/profiles/YourUserName.md. The raw.githack link allows reviewers to preview your changes. Please double check that everything looks good and is working as you hoped before moving on to next section.
NOTE: • If you don't see any changes in your page after editing your file then you need to clear your browser's cache or open your page in your browser's "incognito" or "privacy" mode. You can also press Ctrl+Shift+R or Ctrl+F5 to reload the page with cache cleared. • As MDwiki site is what we use for "production," please always check if everything renders as you expected using raw.githack link. There are different flavors of Markdown. Use GitHub's preview tab for reference only.
Once you have your profile ready, it's time to create a pull request. Click on one of the "Pull request" button as highlighted in the screenshot below.
There are a few things to watch out before clicking on the green "Create pull request" button. Make sure you:
- give the pull request a short and descriptive title (e.g. create YourUserName.md)
- include the raw.githack link to your Markdown profile page in the pull request description
- scroll down the page and verify you used at least 5 different Markdown elements in your profile
Finally, click "Create pull request" button and post the link to your github.io and profile pull request in the gitter chat:
@/all I'm on step 3 - GitHub and Markdown, please look at
https://YourUserName.github.ioand review my profile pull requestLinkToYourPullRequest
Remember, it can take a while for https://YourUserName.github.io to be up and running, so don't worry if you see a 404 when you access the link!
Someone from our team will review the changes and notify you on gitter. Often there will be some feedback from the reviewer for you to address. If that is the case, make changes to your branch and comment on the pull request when done. Any changes you make to your branch will be automatically updated in the pull request. Once you get 3 approving reviews, we will merge your Markdown profile with the main repository.
After the pull request is merged, you'll be able to see your personal page at open-learning-exchange.github.io/#!pages/vi/profiles/<YourUserName>.md. Let us know in the gitter.im chat after you complete this step.
NOTE: Try to add and experiment with as many markdown elements as you can and make your page attractive. A list of sample profile pages can be found here. Be creative.
After your pull request has been approved and merged by OLE staff, you might want to delete the branch that is associated with your pull request. It can keep your remote (yourUserName.github.io on GitHub) repository away from a mess of defunct branches. To delete the defunct branch in your remote repository, you can click the "Delete branch" button in your pull request (see the picture below).
GitHub – Mastering Markdown - The official GitHub Guide for Markdown syntax.
MDWiki – Quick Start - The official MDwiki quick start guide on Markdown syntax.
GitHub - Writing and Formatting - A GitHub help page on how to format and write, along with working with saved replies.
GitHub - How to fork a repo - A more in-depth explanation about how and why we fork repositories.
Other helpful links and videos
Next Section (Step 4) →
In the next step, you will learn more about your community Planet, and the Planet interface.