-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.qmd
258 lines (164 loc) · 11.8 KB
/
index.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
---
title: 'Personal Website using Jupyter Notebook and Quarto'
description: |
A Long But Worth It, tutorial on how to make a personal website out of a jupyter notebook, github account, and quarto.
title-block-banner: true
date: '2023-03-20'
categories:
- tutorial
- quarto
- python
- vscode
code-fold: show
draft: false
citation-location: margin
jupyter: minids
---
![Photo by <a href="https://unsplash.com/es/@glenncarstenspeters?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Glenn Carstens-Peters</a> on <a href="https://unsplash.com/backgrounds/apps/website?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>](./images/image0.jpg){.preview-image}
# Introduction
Quarto to me is one of the best thing ever from Rstudioconf 2022 last year, POSIT (previously Rstudio) marketed it as an open source tool to create documents, presentation, books, website easy and inclusive for python users. This is huge, cause for the longest time, there is not an easy way to create website out of a notebook, nbdev might be one of those people to facilitate this, but not at the support and scale of which R-people get (Xaringan, Blogdown for Hugo, or Distill for Rmarkdown, etc).
# Why Creating A Personal Website
A personal website is a great way to showcase our project to the world. Sure there is even a no-code platform like medium that you can use, but there are couple things I think it fall shorts on:
## Pay Gate Wall
It is good if you are getting paid for what you were sharing on, but if your main purpose is for branding yourself (like me), then a pay gate wall would not do you any good (@fig-paygate). Especially, when you have just started on. Though it is fairly cheap, it is just another stopper for your first audience. Worse, the paid-subscription is only available for certain countries, Indonesia for example is not supported.
![Pay Gate in medium.com](images/image1.png){#fig-paygate}
## Reproducibility
When I do my first data-science project, I wanted to make sure that someone can just follow along and then get the same result as I was. Using platform like medium, I could not really do that, and I believe it was not meant for tutorial in details. Rather it was for an explanatory writing, rather than exploratory writing. Quarto with its rendered codes as an output, makes it easier to do just that. The below code cell is me importing libraries, importing a dataset, and displaying the table.
```{python}
#importing libraries
import pandas as pd
import hvplot.pandas
from bokeh.sampledata.penguins import data as penguins
#displaying first 5 rows
penguins.head()
```
What if I want to show the last 6 rows? I can just change the code.
```{python}
#importing libraries
import pandas as pd
import hvplot.pandas
from bokeh.sampledata.penguins import data as penguins
#displaying first 5 rows
penguins.tail(6)
```
## 3. Contents Ownership
If one day the platform (medium) goes bankrupt, I have no worry because I kept all my posts in a github, and my local folder. If the domain is somehow being hacked, I can just changed it. I own the content, and nobody else.
This gives you not only a total control, but also a freedom to experiment to your heart desires.
<iframe src="https://giphy.com/embed/iCS5WBHrudbqQMp6Fx" width="360" height="360" frameBorder="0" class="giphy-embed" allowFullScreen>
</iframe>
<p><a href="https://giphy.com/gifs/data-own-it-your-iCS5WBHrudbqQMp6Fx">via GIPHY</a></p>
> Of course there are benefits of using low-code platform, but for my use case, I much prefer to have my own personal website.
# Building The Website
Now if you are convinced, let's get to the core of this post, How Do I make one?
<iframe src="https://giphy.com/embed/59WkxrzP5an7Xdh4lb" width="480" height="200" frameBorder="0" class="giphy-embed" allowFullScreen>
</iframe>
<p><a href="https://giphy.com/gifs/thefastsaga-59WkxrzP5an7Xdh4lb">via GIPHY</a></p>
Now I should assume that you know what a github is, know what a terminal is, and know how to google. With that, there are really just three things that you need to have:
1. A github account
2. VS Code[^1]
3. Content (notebook)
[^1]: you *can* just use a notebook, but some of the autocompletion, visual-mode (a powerful mode to make blogging easier) won't work.
With that out of the way, here are the following steps to create your first personal website:
## Creating a Repo
Make a new repository with the same name as your github account. For example, if your github account is *johndoe*, then make a new repository named john.github.io (see @fig-newrepo).
![Creating a New Repo](images/image2.png){#fig-newrepo}
What's cool about this repo is it will be accessible later on as a domain for your personal website, completely free, and secure (https). This of course can be customized with a domain of your choice, but for now, we want to make this as easy as possible.
## Starting from a Notebook
Let's make a content, using jupyter notebook, with a combination of code cells and markdown cells. I am gonna use the content in this post, where I load a libraries, dataset from palmerpenguins, and then I will do some plotting using altair to spice things up, cause why not. See below @fig-notebook for example.
```{python}
#importing libraries
import altair as alt
from bokeh.sampledata.penguins import data as penguins
import warnings
warnings.simplefilter(action='ignore', category=FutureWarning)
#plotting
brush = alt.selection(type='interval')
points = alt.Chart(
data=penguins,
title="Palmer Penguins Dataset",
).mark_circle(size=60).encode(
alt.X('bill_length_mm', scale=alt.Scale(domain=[30,60])),
alt.Y('bill_depth_mm', scale=alt.Scale(domain=[12,22])),
color='species',
).add_selection(
brush
)
bars = alt.Chart(penguins).mark_bar().encode(
y='island',
color='island',
x='count(island)'
).transform_filter(
brush
)
points & bars
```
![Example Notebook](images/image4.png){#fig-notebook}
## Create a Project
The first step is to create a set of folders for website project, using quarto by executing the following command inside the project folder:
```{bash}
mkdir posts
quarto create-project . --type website
```
which will output the following @fig-output-project, essentially the `post` folder would be where we keep our blogpost files.
![Output Projects](images/image5.png){#fig-output-project}
## Convert Notebook to Quarto Markdown
The second step is to convert the jupyter notebook file (example.ipynb) to quarto markdown file (example.qmd) by running the following command:
```{bash}
quarto convert ./example.ipynb
```
which will create an output of qmd file which is important, because this would then be rendered to html (as shown in @fig-output-render) by running the following command:
```{bash}
quarto render
```
![Output Render](./images/image6.png){#fig-output-render}
## Setting-up the Website
YAML file is basically where we fine tune our website settings. For this case, we need to move the `example.qmd` file to `post` folder, and *add* the qmd file inside the navbar, below the `about.qmd` as shown in @fig-yaml
![YAML setting](./images/image7.png){#fig-yaml}
## Previewing the Website
All things set, now all we need to do is preview our website by running the following command:
```{bash}
quarto preview
```
which will output our new website inside a browser as shown in the following @fig-preview. This is a preview mode which means, any changes made to the website, it will be rendered and displayed real-time.
![Website Preview](./images/image8.png){#fig-preview}
Voila! You got it done! Congrats!
## Deploying the Website
There is a documentation on [Quarto](https://quarto.org/docs/publishing/github-pages.html) to do this, but in layman terms, there are essentially three things to do:
- Create a `docs` folder and set the output to be that folder in \_quarto.yml file as shown in @fig-docs below
![docs settting](./images/image9.png){#fig-docs}
- Set the website repo setting to use the docs folder as the branch source as shown in @fig-reposettting below
![repo settting](./images/image10.png){#fig-reposettting}
- Push your local Repo to the Github!
```{bash}
git add .
git commit -m "my first website"
git push
```
and you should see your website is up and running after the builds and deployment as shown in @fig-builds finished!
![Builds Up and Deployment](./images/image11.png){#fig-builds}
:::{.callout-important}
Since this is a static pages, we will have to run `quarto-render` everytime before pushing it to the github. Otherwise, it may appear in our preview-mode, but will not show up in the website online.
:::
# Pro Tips
## 1. Make A Homepage
If you have your website deployed, congrats! However, if you stay, I can assure you that it will make your website much better.
Some nicer things to do for your website is to render the index.qmd in the root folder as a listing, so any post in your post folder will be listed as a content, as shown in @fig-listing below:
![Setting Up the Website](./images/image12.png){#fig-listing}
Here is what I did to the initial website:
1. Make a folder inside `posts`, create a `001-first-post` folder, and change the filename to `index.qmd`
2. Edit the `index.qmd` in the `root` folder to list the contents
3. Edit the `_quarto.yml` file back to its original setting.
With this setting, you will have a nicer homepage like @fig-homepage below:
![Homepage](./images/image13.png){#fig-homepage}
## 2. Use Quarto in VSCode
Although so far we can get by just by using jupyter notebook, we were missing out (big time) in quarto extension capabilities. Autocompletion, autosuggestions, which are available in VSCode but not the jupyter notebook.
Using VSCode and Quarto, we can easily shift between visual-mode and source-mode, for a nicer GUI. You can just right-click and select `edit in visual-mode` and it will automatically brings you to a GUI version of the markdown.
> From there, we can change the heading-style, bold, italic, add numbers, lists, picture, callnote, a very powerful GUI for markdown! Loved it!
Here is the comparison side-by-side in @fig-comparison:
![Source-mode vs Visual-mode](./images/image14.png){#fig-comparison}
:::{.callout-tip}
One of the nicest things that I used *A LOT* is the ability to just copy-paste an image from clipboard to a qmd file via visual-mode, and it will automatically create a folder named images, save the image we pasted into the folder, and displayed it (by referencing) into the qmd file. All happen instaneously!
:::
## 3. Craving for More?
There is a good chance that this blogpost would not be enough for you after you add some more contents, and wanted to change some views/ aesthetics of the websites. My suggestion has always been to the excellent Quarto [documentations for website](https://quarto.org/docs/websites/), Mickael make a repo dedicated just for Quarto (extensions, slides, tutorial and alike) make sure to check his [repo](https://github.com/mcanouil/mickael.canouil.fr), follow him also in twitter, as I always find the latest new things from him from there like this one:
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">🤖 From <a href="https://twitter.com/hashtag/AwesomeQuarto?src=hash&ref_src=twsrc%5Etfw">#AwesomeQuarto</a>: 'How to add some personality to your Quarto Blog' (<a href="https://t.co/nK3j7rPty1">https://t.co/nK3j7rPty1</a>)<br>A blog post sharing some of the added features and tweaks users can make on top of the standard blog templates to inject some personality into their blog.<a href="https://twitter.com/hashtag/QuartoPub?src=hash&ref_src=twsrc%5Etfw">#QuartoPub</a></p>— Mickaël CANOUIL (@MickaelCanouil@fosstodon.org) (@MickaelCanouil) <a href="https://twitter.com/MickaelCanouil/status/1637424613654413315?ref_src=twsrc%5Etfw">March 19, 2023</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>