|
1 | 1 | # GitHub Pages |
2 | 2 | {id: github-pages} |
3 | 3 |
|
4 | | -## Why use version control? |
5 | | -{id: why-use-version-control} |
6 | | - |
7 | | -* Everyone uses some version control. (e.g. by copying the document with a date suffix). |
8 | | -* There are many version control systems (VCSs). |
9 | | -* `git` is the de-facto standard these days. It is open source and free. It is integrated in many tools. |
10 | | -* [GitHub](https://github.com/) is the most popular cloud-based hosting service for `git` repositories with many extra features. |
11 | | - |
12 | | -* In this session we will use `git` only via the web-site of GitHub. |
13 | | - |
14 | | -## GitHub Account |
15 | | -{id: github-account} |
16 | | - |
17 | | -* If you don't have an account yet on [GitHub](https://github.com/) then create one now. |
18 | | -* It should be personal. It will remain with you for your life. (or the life of GitHub) |
19 | | -* It should not be related to your current educational institute or workplace or this presentation or course. |
20 | | - |
21 | | -* My account is [szabgab on GitHub](https://github.com/szabgab/). It is my nickname almost everywhere on the Internet. It is even the address of [my web site](https://szabgab.com/). |
22 | | - |
23 | | -## Repositories |
24 | | -{id: github-repositories} |
25 | | - |
26 | | -* On GitHub you can store as many `git` repositories as you like. They can be either private or public. |
27 | | -* The names of the repositories are arbitrary. |
28 | | -* https://github.com/USERNAME/REPO-NAME |
29 | | -* https://github.com/ORGANISATION/REPO-NAME |
30 | | - |
31 | | -* Some repository names have special meanings. |
32 | | -* USERNAME |
33 | | -* USERNAME.github.io |
34 | | - |
35 | | -For me they are |
36 | | -* [https://github.com/szabgab/szabgab](https://github.com/szabgab/szabgab) |
37 | | -* [https://github.com/szabgab/szabgab.github.io](https://github.com/szabgab/szabgab.github.io) |
38 | | - |
39 | | - |
40 | | -## GitHub Avatar |
41 | | -{id: github-avatar} |
42 | | - |
43 | | -* Update your profile, add information about yourself. |
44 | | -* Add a picture or an avatar of you to make your account more recognizable. |
45 | | -* Your profile / Edit profile / ... |
46 | | - |
47 | | -* The big text comes from the `README.md` file of the [szabgab/szabgab](https://github.com/szabgab/szabgab) repository. |
48 | | - |
49 | | -## Setting up GitHub page |
50 | | -{id: setting-up-github-page} |
51 | | - |
52 | | -* Create a GitHub repository called USERNAME.github.io (using your own USERNAME). |
53 | | -* For user [szabgab](https://github.com/szabgab/) it is [szabgab.github.io](https://github.com/szabgab/szabgab.github.io). |
54 | | -* Make the new repository public so everyone will be able to see the source. |
55 | | -* Check the "Add a README file" checkbox. |
56 | | - |
57 | | -* Check the `Actions` tab to see the process generating the web site. |
58 | | - |
59 | | -* Visit https://USERNAME.github.io (it may take a few minutes to update) |
60 | | -* For user szabgab it is [szabgab.github.io](https://szabgab.github.io/). |
61 | | -* For GitHub Organizations it is exactly the same process. |
62 | | - |
63 | | -## HTML - view source |
64 | | -{id: html-view-source} |
65 | | - |
66 | | -* Web sites are built using HTML. |
67 | | -* Look at the source of the page. That's HTML. We don't want to write that. |
68 | | -* So we'll use Markdown and an some tool that will convert Markdown to HTML. |
69 | | - |
70 | | - |
71 | | -## GitHub page with Jekyll |
72 | | -{id: github-page-with-jekyll} |
73 | | - |
74 | | -* [Jekyll](https://jekyllrb.com/) a static site generator |
75 | | - |
76 | | - |
77 | | -* Many [Static Site Generators](https://jamstack.org/generators/). |
78 | | - |
79 | | - |
80 | | -## Markdown |
81 | | -{id: markdown-links} |
82 | | - |
83 | | -* [Markdown](https://daringfireball.net/projects/markdown/) |
84 | | -* [GitHub flavored Markdown](https://github.github.com/gfm/) |
85 | | - |
86 | | - |
87 | | -## Markdown |
88 | | -{id: markdown} |
89 | | - |
90 | | -* Titles: One or more `#` followed by the the title |
91 | | -* **Bold** `**` on both sides |
92 | | -* _Italic_ `_` on both sides |
93 | | - |
94 | | -* Horizontal separator `---`. |
95 | | - |
96 | | -* Link to some other site. e.g. to the slides. |
97 | | - |
98 | | -* Unordered list. `*` |
99 | | -* Ordered list (both with ordered numbers and with `1.`-s) |
100 | | - |
101 | | -* Add image from other site `` |
102 | | -* Upload an image and show it. |
103 | | - |
104 | | -* Use the `img` HTML element to set the size of the image. |
105 | | - |
106 | | -``` |
107 | | - |
108 | | -``` |
109 | | - |
110 | | -* Table |
111 | | - |
112 | | -* Verbatim with back-ticks. |
113 | | -* Inline with one-tick. |
114 | | -* Multi-line with 3-ticks. Add also programming language for highlighting. |
115 | | -* Indenting 4 spaces also works. |
116 | | - |
117 | | - |
118 | | -## Add page |
119 | | -{id: add-another-page} |
120 | | - |
121 | | -* Create a file called `about.md`. |
122 | | -* Visit https://USERNAME.github.io/about |
123 | | -* Show how to link to it from the main page. |
124 | | - |
125 | | - |
126 | | - |
127 | | - |
128 | | -## Customized 404 Page not found |
129 | | -{id: page-not-found} |
130 | | - |
131 | | -* Visit a page that does not exist. |
132 | | -* Create the `404.md` file to provide custom error message. |
133 | | - |
134 | | - |
135 | | -## Jekyll themes |
136 | | -{id: jekyll-themes} |
137 | | - |
138 | | -* [themes](https://pages.github.com/themes/) |
139 | | -* Create `_config.yml` with |
140 | | - |
141 | | -``` |
142 | | -theme: jekyll-theme-cayman |
143 | | -``` |
144 | | - |
145 | | - |
146 | | -## Themes layout |
147 | | -{id: theme-layout} |
148 | | - |
149 | | -* [themes](https://pages.github.com/themes/) |
150 | | -* [Cayman in GitHub](https://github.com/pages-themes/cayman) |
151 | | -* [Cayman demo](https://pages-themes.github.io/cayman/) |
152 | | -* [`_layouts/default.html`](https://github.com/pages-themes/cayman/blob/master/_layouts/default.html) look at the template tags to learn about config options. |
153 | | - |
154 | | - |
155 | | -## Site-wise configuration |
156 | | -{id: site-wise-configuration} |
157 | | - |
158 | | -* In `_config.yml` |
159 | | - |
160 | | -In the `_config` file we can add a field called `description:`. It will provide the content for the subtitle of the header. |
161 | | - |
162 | | -``` |
163 | | -description: Some text |
164 | | -``` |
165 | | - |
166 | | - |
167 | | - |
168 | | - |
169 | | - |
170 | | - |
171 | | -## Page-specific configuration - frontmatter |
172 | | -{id: page-specific-configuration} |
173 | | - |
174 | | -* At the top of the .md files |
175 | | -* [Frontmatter documentation](https://jekyllrb.com/docs/frontmatter/) |
176 | | - |
177 | | - |
178 | | -``` |
179 | | ---- |
180 | | -title: About the szabgab page |
181 | | ---- |
182 | | -``` |
183 | | - |
184 | | - |
185 | | -## JavaScript code |
186 | | -{id: javascript-code} |
187 | | - |
188 | | - |
189 | | - |
190 | | -* One can include plain HTML in the md file. So include `script` tags. |
191 | | -* The code should come at the end to have the DOM available already. |
192 | | - |
193 | | -## Load jQuery and add jQuery code |
194 | | -{id: load-jquery-code} |
195 | | - |
196 | | - |
197 | | - |
198 | | - |
199 | | -When you change the JavaScript file, make sure it is reloaded! Browser cashing can cause you a bad day. |
200 | | - |
201 | | - |
202 | | - |
203 | | -## Add a JSON file, load it with jQuery and display the content |
204 | | -{id: load-json-file} |
205 | | - |
206 | | - |
207 | | - |
208 | | - |
209 | | - |
210 | | - |
211 | | - |
212 | | -## HTML pages |
213 | | -{id: html-pages} |
214 | | - |
215 | | - |
216 | | -* Create a file called `about.html`. |
217 | | - |
218 | | - |
219 | | - |
220 | | -* Note: the `.html` files take precedence over the `.md` files! |
221 | | - |
222 | | - |
223 | | -## Examples |
224 | | -{id: examples} |
225 | | - |
226 | | - |
227 | | -* [rustatic](https://rustatic.code-maven.com/) - [source](https://github.com/szabgab/rustatic/) using Jekyll. |
228 | | -* my simple site [github.szabgab.com](https://github.szabgab.com/) - [source](https://github.com/szabgab/real-szabgab.github.io) using only Markdown files and the default Jekyll processor on GitHub pages. |
229 | | -* [Kantoniko](https://kantoniko.com/) - [source](https://github.com/kantoniko/) - using Python combining data from many repositories. A dictionary and content in Ladino. Written in Python collecting data from multiple repositories. |
230 | | -* my personal site [szabgab.com](https://szabgab.com/) - [source](https://github.com/szabgab/szabgab.com) - using Perl. |
231 | | -* [Perl Weekly](https://perlweekly.com/) - [source](https://github.com/szabgab/perlweekly) - Perl, generate the site locally and push the HTML files as well. |
232 | | - |
233 | | -* The students of [WIS Python course started in 2024-04](https://github.com/szabgab/wis-python-course-2024-04) |
234 | | -* The students of [WIS Python course started in 2024-11](https://github.com/szabgab/wis-python-course-2024-11) |
235 | | - |
236 | | - |
237 | | -* [Planet Perl](https://perl.theplanetarium.org/) - [source](https://github.com/PerlToolsTeam/planetperl) using Perl. |
238 | | -* [Forem Reports](https://forem.code-maven.com/) - [source](https://github.com/szabgab/forem-reports). |
239 | | -* [(Rust) virtual events](https://events.code-maven.com/) - [source](https://github.com/szabgab/virtual-events). |
240 | | -* [Ruby Digger](https://ruby-digger.code-maven.com/) - [source](https://github.com/szabgab/ruby-digger) |
241 | | - |
242 | | -* [Rust Maven](https://rust.code-maven.com/) - [source](https://github.comr/szabgab/rust.code-maven.com/) - [Rust Maven SSG](https://ssg.code-maven.com/) written in Rust. |
243 | | -* [Rust news](https://rust-news.code-maven.com/) written in Rust, collecting RSS/Atom feeds and generating the web site. |
244 | | - |
245 | | -* Code Maven sites |
246 | | -* Perl Maven sites |
247 | | - |
248 | | -* [slides](https://slides.code-maven.com/) - [source](https://github.com/szabgab/slides/) - [generator](https://github.com/szabgab/slider-py) written in Python. |
249 | | - |
250 | | -* [rust.org.il](https://rust.org.il/) - [source](https://github.com/szabgab/rust.org.il/) written in Rust. |
251 | | -* [python.org.il](https://python.org.il/) - [source](https://gitlab.com/hamakor/python.org.il/) is written in Python but it is hosted on GitLab pages. |
252 | | - |
253 | | -## Rename repository |
254 | | -{id: rename-repository} |
255 | | - |
256 | | -* Rename repository so I'll be able to demo this later as well. |
257 | | -* Show how to access the web site now. |
258 | | - |
259 | | -## Open Issue |
260 | | -{id: open-issue} |
261 | | - |
262 | | -* Show how to open an issue on the repository with a link to your site and repository. |
263 | | -* Show with my own site. |
264 | | - |
265 | | -## Add table of people |
266 | | -{id: add-table-of-people} |
267 | | - |
268 | | -* Take the data from the issue and add it to the table listing the web sites. |
269 | | - |
0 commit comments