You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/tut/5-0-Make-your-own-documentation.md
-128Lines changed: 0 additions & 128 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,131 +14,3 @@ Make your own documentation repository and turn it into a GitHub Pages site
14
14
{: .fs-6 .fw-300 }
15
15
16
16
---
17
-
18
-
## 1. Make your GitHub repository
19
-
20
-
Every GitHub pages site starts off as a simple repository.
21
-
22
-
Create a new repository for your documentation by going to your repositories and selecting "New".
23
-
24
-
Next git it a name, description, and add a README file. I've chosen not to add a license here as I have a preference for one which is not in the list of default licenses provided by GitHub.
25
-
26
-
Click "Create Repository" Ta-da! You have a repository! 🎉
27
-
28
-
29
-
30
-
## 2. Update your README.md
31
-
32
-
Your README is your landing page for your repository on GitHub. Depending on the Pages theme you chose, it may also be rendered as the "home" page on your site.
33
-
34
-
Your README should contain all the information someone needs to understand what your project is about and how they can contribute. Some suggested section headings for your README are below.
35
-
36
-
- Welcome
37
-
- What are we doing
38
-
- The problem
39
-
- The solution
40
-
- Who are we
41
-
- What do we need
42
-
- Contact Us
43
-
- Find out more
44
-
- Thank you
45
-
46
-
To get a quick outline of the README structure (and to differentiate it from the one automatically created by GitHub), I have chosen to edit the page in GitHub directly, and add the section headings in [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
47
-
48
-
To save your changes, describe what you did in the commit message, then press "commit"
Now the magic! Turn this simple collection of files into something which looks like a user friendly (and not GitHub scary!) website!
75
-
76
-
Go into your site settings and scroll down to the "GitHub Pages section". Change the "Source" into your "master" branch and click "save".
77
-
78
-
Next click "Choose a theme" and pick from one of the preselected options provided by GitHub. One of these theme might be fine for your purposes but there are hundreds of other free themes we can chose from (more about that below). For now, I'm going to pick a theme at random, as this will create the necessary file we need to modify to put in our own selection of theme.
79
-
80
-
Click "Select Theme" to return to your setting page. You will now see that the URL of your pages site is listed under the GitHub Pages section. Take A look!
81
-
82
-
Woohoo! You have a website! 🎉
83
-
84
-
85
-
86
-
## 6. Change your theme
87
-
88
-
There are hundreds of different (free!) jekyll theme to play around with. Some are intentionally designed for documentation, with simple navigation and minimal "frills". Others are designed for blogs with the regular addition of tagged posts. Others are designed for graphical portfolios, with an emphasis on bold pictures. Take a look around [https://jekyllthemes.io/free](https://jekyllthemes.io/free) to see which you like!
89
-
90
-
If you chose to use a theme other than one GitHub already supports, you can use this as a "remote" theme. This simply means you have to tell GitHub where the theme is hosted (where the developed keeps all the code!) and point your page to that address. Take a look at this [blog about remote themes to learn more](https://github.blog/2017-11-29-use-any-theme-with-github-pages/).
91
-
92
-
To change your theme, update the "_config" file which was created automatically by GitHub when you created your pages site. Edit this file in GitHub directly to include the "remote_theme" tag (as described on the [remote themes blog](https://github.blog/2017-11-29-use-any-theme-with-github-pages/)), and the name of the developer and theme you have chosen (the name of their repository).
While you're here, it's a good idea to add the URL of your pages site to the "About" description on your GitHub repository. This is useful to help people find your pages site if they land on your repository first. Remember, your GitHub repository and your Pages site both exist as separate entities (at separate URLs), with the content repeated on both but "rendered" differently at each URL.
At the moment, your repository exists only online. This is fine for basic editing, but it you want to be able to work on your site and documentation offline, you'll want to have a copy of everything on your own computer. You can also use some neat tools for editing markdown once you have a copy of the repository locally.
106
-
107
-
Getting a local copy of your repository is called "cloning" in GitHub terms.
108
-
109
-
To clone your repository to your local computer, click the "Code" button on your GitHub page, and click the button to copy the https address of your repository.
110
-
111
-
Next in your terminal navigate to where you want your repository code to live and enter the below:
112
-
```
113
-
git clone [https address for your repo]
114
-
```
115
-
116
-
Boom! You have a local copy of your code 💃.
117
-
118
-
119
-
120
-
Now dig into the "how to" guide of your chosen theme to learn what you can add to make your pages site 💯.
121
-
122
-
Pro-tip: Search the internet for examples where other people have used the same theme as you, then did about in their GitHub repository to see how they achieved it. You can simply search for the "theme tag" which is often automatically rendered (and not removable) from free jekyll theme sites. For example: "This site uses Just the Docs, a documentation theme for Jekyll."
123
-
124
-
In the below I've edited my repo in atom. I've added a few pages, and the front matter (text at the top) to define the order I want pages to appear in, and whether they should have sub-pages ("children").
125
-
126
-
Once you've made a few changes, simply add, commit and push them to your repo!
127
-
128
-
129
-
130
-
It takes a little while for your pushed changes to appear on your site (especially if they are more complex things than adding/removing words). Be patient ⏳. Wait for them to arrive and see what you have created!
You are now a GitHub Pages and documentation hero! 🙌🏻 🙌🏼 🙌🏽 🙌🏾 🙌🏿
137
-
138
-
Edit your pages and play with your theme. The site you are now reading is the same which I started in the recordings above, just now it's pretty 🌺
139
-
140
-
Don't forget to add, commit and push your changes at regular intervals to see how they have taken effect. It might be easiest to start with little changes and get your structure right before attempting anything to grand!
141
-
142
-
Some themes prefer just markdown, but most (maybe all?!) will also accept html, so anything which can be achieved in html can also go into your GitHub Pages site.
143
-
144
-
Go forth and document, with version control! 🤘🏻 🤘🏼 🤘🏽 🤘🏾 🤘🏿
0 commit comments