Skip to content

Commit afb67eb

Browse files
amyheatheramyheather
committed
feat(basic_structure): working on page
1 parent 5891572 commit afb67eb

File tree

1 file changed

+171
-8
lines changed

1 file changed

+171
-8
lines changed

‎pages/basic_structure.qmd‎

Lines changed: 171 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,177 @@
22
title: Basic structure
33
---
44

5-
explain basic structure of quarto website
5+
## Introduction to RStudio
66

7-
i.e., walkthrough of provided codespace.
7+
TODO
88

9-
then, quarto render and quarto preview
10-
(or perhaps that's another page?)
11-
explain: what is terminal
12-
(OR show just via buttons?)
9+
<!-- Rough notes...
1310
14-
https://quarto.org/docs/books/book-output.html
15-
HTML books are at their core Quarto Websites with some special navigational behavior built in.
11+
BE SUPER CLEAR that this is just somewhere to run quarto and that focus of this session is not on code (though will do at the very end).
12+
13+
If youre not someone who has coded / used R
14+
no worry
15+
not needed for session
16+
and not needed for quarto
17+
18+
so why are we using rstudio?
19+
20+
explain- need an IDE - one of the really cool things they can do is include executable code e.g., R and Python - come onto that at the end - but also, can make sites without
21+
22+
best interfaces for making quarto sites? things like rstudio, positron and vscode.
23+
they just are what exist.
24+
25+
explain basic interface
26+
- text editor
27+
- console / terminal / background jobs - explain each
28+
- environment
29+
- files, help, plots
30+
31+
we are going to look at files...
32+
-->
33+
34+
## Introduce to Quarto websites
35+
36+
We'll be creating a **Quarto website**, but it's worth knowing that Quarto can produce many things. See the [Quarto documentation](https://quarto.org/docs/guide/) for examples - options include:
37+
38+
* Presentations
39+
* Dashboards
40+
* Manuscripts
41+
* Documents
42+
* Books
43+
44+
A simple website project just needs **two key files**:
45+
46+
1. `_quarto.yml`
47+
2. `index.qmd`
48+
49+
### `_quarto.yml`
50+
51+
This is file defines your **project settings** and **website structure**.
52+
53+
TODO: Add explanation. A yml file is YAML. plain text format. uses key-value pairs to store settings. YAML ("YAML Ain't Markup Language") is a simple format using key–value pairs, like:
54+
55+
Below is an example from [quarto-template](https://github.com/pythonhealthdatascience/quarto-template){target="_blank"}. Hover over each line to see an explanation:
56+
57+
```yaml
58+
project: # <1>
59+
type: website # <1>
60+
61+
website: # <1>
62+
title: "Quarto Template" # <2>
63+
favicon: images/exeter.png # <3>
64+
navbar: # <4>
65+
right: # <5>
66+
- icon: github # <5>
67+
text: GitHub # <5>
68+
href: https://github.com/pythonhealthdatascience/quarto-template/ # <5>
69+
sidebar: # <6>
70+
- logo: images/exeter.png # <7>
71+
contents: # <8>
72+
- text: Overview # <8>
73+
href: index.qmd # <8>
74+
- pages/TODO.qmd # <8>
75+
```
76+
77+
1. **Website:** Defines that this project builds as a website.
78+
2. **Website title:** Appears in broswer tab and navbar.
79+
3. **Favicon:** The small icon shown on the tab (often a logo).
80+
4. **Navbar:** The navigation bar across the top of your site.
81+
5. **GitHub link:** Adds a GitHub icon on the right side of the navbar linking to the repository (which contains the source files for the site).
82+
6. **Sidebar:** Displays navigation links down the left-hand side.
83+
7. **Logo:** The image shown at the top of the sidebar.
84+
8. **Sidebar contents:** Lists website pages. Will list using page titles by default, but can override with `text` (title to use) and `href` (path to file).
85+
86+
::: {.callout-note title="Optional extra: books" collapse="true"}
87+
88+
A **Quarto book** is basically a website with chapter-style navigation. Under the hood, it's still a Quarto website - just organised a little differently.
89+
90+
See the [books guide](https://quarto.org/docs/books/book-output.html) for more information.
91+
92+
Example:
93+
94+
```yaml
95+
project:
96+
type: book
97+
98+
book:
99+
title: "Quarto Template"
100+
favicon: images/exeter.png
101+
chapters:
102+
- text: Overview
103+
href: index.qmd
104+
- pages/TODO.qmd
105+
navbar:
106+
right:
107+
- icon: github
108+
text: GitHub
109+
href: https://github.com/pythonhealthdatascience/quarto-template/
110+
sidebar:
111+
logo: images/exeter.png
112+
```
113+
114+
:::
115+
116+
### `index.qmd`
117+
118+
A `.qmd` file is a **Quarto Markdown** document.
119+
120+
> If you're familiar with R Markdown (`.Rmd`), these are similar, but `.qmd` is more flexible.
121+
122+
`index.qmd` servers as the **homepage** of your website.
123+
124+
Each `.qmd` file begins with **YAML front matter**, enclosed by three dashes (`---`). This defines metadata such as the page title.
125+
126+
> Alternative way of doing this would be `# My homepage`. TODO: SO WHY DO IT IN YAML?
127+
128+
Below that is the page. Here we just have one sentence: `This is my homepage.`.
129+
130+
```qmd
131+
---
132+
title: My homepage
133+
---
134+
135+
136+
This is my homepage.
137+
```
138+
139+
## Rendering your website
140+
141+
**Rendering** means converting your Quarto source files into the final website - a colelction of `.html` pages that live inside a folder called `_site`.
142+
143+
To render in RStudio...
144+
145+
1. Open `index.qmd` in the editor.
146+
147+
[SCREENSHOT]
148+
149+
2. Click the blue **Render** button (the arrow icon) at the top of the editor.
150+
151+
[SCREENSHOT]
152+
153+
RStudio will:
154+
155+
* Create the `_sites/` folder containing your rendered site.
156+
* Open a **live preview** in your browser.
157+
158+
TODO: EXPLAIN LIVE PREVIEW url... its local host... display via browser...
159+
160+
::: {.callout-tip title="Troubleshooting"}
161+
162+
The preview may not open automatically if your browser blocks the pop-up. To resolve this, you should either:
163+
164+
* Click to allow pop-ups in your browsers, then click **Render** again.
165+
* Go to the **Background Jobs** tab in the bottom left. This is where lgos from rendering quarot site are shown. Here, you will find the preview URL. Copy and paste this into browser.
166+
167+
:::
168+
169+
[SCREENSHOT]
170+
171+
### Rendering from the terminal
172+
173+
You can also build your site using command-line tools. The terminal is simply a text-based way to type commands directly, rather than clicking buttons.
174+
175+
Two helpful commands are:
176+
177+
* `quarto render` - builds your website.
178+
* `quarto preview` - builds and opens a live-updating preview.

0 commit comments

Comments
 (0)