OSDC lesson 2: Create a website for you and your projects on github
Tags: osdc, opensource, programming, github
Published: 2023-01-15 15:05:00

---
series: OSDC
---

# GitHub pages
## Create my own website on GitHub step by step
### Create a repository *github_username.github.io*
* Within [my GitHub](https://github.com/ShulyAvraham) create a new repository:
  * Click `Repositories`
  * Click `New` 
  * Repository name must be: *github_username.github.io*, in my case [shulyavraham.github.io](shulyavraham.github.io)
  * Click `Create repository`
  * So, now I have a [new repository](https://github.com/ShulyAvraham/shulyavraham.github.io/)
* Create a new file named *index.md* in the new repo 
  * Add some markdown text to the file and click `Commit new file`

### Generate the pages
Create the pages
* Click `Settings` on the top menu  
* Click `Pages` on the left menu
* Select `Deploy from branch` in the `Source` drop down 
* Select the `main` branch
* You can select the directory which will server the pages, either `root` or `docs`
* Click `Save`

### View my website
Now [my website](shulyavraham.github.io) was created with an index page
* Go to the URL [shulyavraham.github.io](shulyavraham.github.io) in the browser
* You should see the index page you crated previously

### Edit the website and add new pages
* The markdown file can now be edited and committed to design the page
  * This is now my own project, so I can `Commit changes` to my own repo
  * Any commit to the page will result in the deployment of the web page, which I can view on [my website](shulyavraham.github.io)
  * GitHub automatically generates HTML from my markdown files using [Jekyll](https://jekyllrb.com/) 

I can now create more pages in an .md format which will be generated to HTML when committed.
* Create a new file **about.md** and edit it
* Link to the new page from the index page
  * Edit **index.md** and add:
```
[Link to about](about)
```

### Configure my web pages theme
  * Go to [my repo](https://github.com/ShulyAvraham/shulyavraham.github.io)
  * Create a new file in the root dir `Add file`->`Create new file`->`File name`: **'_config.yml'**
  * Edit the file to add a theme and title to my pages
```
theme: jekyll-theme-cayman
title: ShulyA's GitHub Page 
```
  * `Commit new file`
  * View [my website](shulyavraham.github.io) with the new theme (it may take a few seconds for the changes to take effect)

[Supported themes for GitHub pages](https://pages.github.com/themes/)

To use one of the supported themes add the following to the **_config.yml** file
```
remote_theme: pages-themes/architect@v0.2.0 # depending on the selected theme
plugins:
- jekyll-remote-theme # add this line to the plugins list if you already have one
```
### Use your own domain to redirect to the GitHub site
3 things must happen, the first 2 are external to GitHub
1. You have your own domain name e.g. github.shulyavraham.com
2. Configure your host provider so that your hostname will map to GitHub
3. Add a file called **CNAME** to your GitHub repo, and edit it to include the hostname, e.g.
```
github.shulyavraham.com
```
## Add other repositories as subfolders of the [main site](shulyavraham.github.io)
If I have other repos from which I generate GitHub pages, they will automatically appear as [sub folders](shulyavraham.github.io/qqrq) of my [main site repo](shulyavraham.github.io)
* Create a new repo **qqrq**
* Go to `Settings`->`Pages`->`Save`
* The new repo's site pages will be generated and added as [sub folder](shulyavraham.github.io/qqrq) to the main repo website

## Some tips
### Embed an image from the web on my page
* Search for an image on google
* Select the image
* Right click the image and select `Copy image address`
* In the markdown file add:
```
![](http://the_image_address/image_name.jpg)
```

### Modify the main index page to be served from **/docs** rather than **/root**
In case you initially chose to serve the website from the /root dir, but decided to change it to the /docs dir
* Go to `Settings`->`Pages`->`Branch`->Select `/Docs`->`Save`