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
# Source for [R Contributor Site](https://contributor.r-project.org/)
2
2
3
+
The website is built with [Quarto](https://quarto.org)
4
+
3
5
## Website structure
4
6
5
-
The top-level pages linked in the menu are in correspondingly named markdown files, e.g.
7
+
The top-level pages linked in the menu are in correspondingly named .qmd files, e.g.
6
8
7
9
| Menu item | Markdown file | Relative URL |
8
10
|-------------|---------------|--------------|
9
-
| Home |`index.md`|`/`|
10
-
| Slack Group |`slack.md`|`/slack`|
11
+
| Home |`index.qmd`|`/`|
12
+
| Slack Group |`slack.qmd`|`/slack`|
11
13
12
-
You can create sub-pages by creating a folder with an `index.md` file. Any further markdown pages within that folder will be sub-pages under that, e.g.
14
+
You can create sub-pages by creating a folder with an `index.qmd` file.
15
+
Any further markdown pages within that folder will be sub-pages under that, e.g.
You can edit the markdown files on the `main` branch and the changes will be automatically deployed to the live site once the changes are committed. If you edit the files directly on GitHub using the browser editor, then you can use the Preview tab to check the formatting before committing.
24
+
You can edit the .qmd files on the `main` branch and the changes will be automatically deployed to the live site once the changes are committed. If you edit the files directly on GitHub using the browser editor, then you can use the Preview tab to check the formatting before committing.
22
25
23
26
## Substantial editing
24
27
25
28
If you are making substantial changes, e.g. adding a new page, or making changes that require collaborating editing/review before being pushed, create a branch and make the changes there.
26
29
27
-
Any changes pushed to a different branch will not be automatically deployed to preview. so if the GitHub editor preview is not sufficient (i.e. you are doing more than editing a single page) it is best to clone the repo and make your changes locally.
30
+
Any changes pushed to a different branch will not be automatically deployed to preview, so if the GitHub editor preview is not sufficient (i.e. you are doing more than editing a single page) it is best to clone the repo and make your changes locally.
28
31
29
32
### Previewing locally
30
33
31
-
To preview the site locally, you will need to install Jekyll, see https://jekyllrb.com/docs/ for installation instructions for common operating systems.
34
+
To preview the site locally, you will need to install Quarto, see https://quarto.org/docs/get-started/.
32
35
33
-
To build the site and make it available on a local server, run the following command in a terminal from the top level directory of the locally cloned repository.
36
+
To build the site and make it available on a local server, run the following command in a terminal from the top level directory of the locally cloned repository:
34
37
35
38
```
36
-
bundle exec jekyll serve
39
+
quarto preview
37
40
```
38
41
39
-
If you use RStudio, you can open this `README.md` file and use `Ctrl/Cmd + Alt + Enter` to send the above line to the terminal.
40
-
41
-
Open http://localhost:4000 in your browser to preview the site. The site is repeatedly rebuilt, so if you make changes to the markdown files and save them, you should see the changes straight-away. Use `Ctrl/Cmd + C` to stop locally serving the site.
42
-
43
-
You will need to restart the server if you add/remove items from the menu.
44
-
45
42
### Creating pages
46
43
47
44
Please use the following YAML fields when creating new pages:
48
45
49
46
---
47
+
title: The title
50
48
description: Short description, less than 160 characters.
51
-
layout: custom
49
+
image: your-image.png
52
50
---
51
+
52
+
The description is used to create cards when sharing links on social media but will not appear on the page itself.
53
53
54
-
The layout should always be `custom`.
55
-
The description is used to create cards when sharing links on social media.
56
-
The title and image (including alternative text) are automatically taken from the page content, using the first `<h1>` header and image respectively.
57
-
The image file should be in the same directory as the markdown file.
54
+
If you don't specify an image in the YAML, an the first image on the page will be used as the image for social media cards (including alternative text).
55
+
The image file should be in the same directory as the .qmd file.
58
56
JPG, PNG, WEBP and GIF formats are supported (only the first frame of an animated GIF will be used).
59
57
60
58
You can check how the card will look using the following validators:
@@ -70,34 +68,23 @@ as that property is not required.
70
68
71
69
### Editing the menu
72
70
73
-
To edit the menu you need to edit the `navigation` field of `_config.yml`.
71
+
To edit the menu you need to edit the `navbar` field of `_quarto.yml`.
74
72
75
73
To add a new page, add a new element with the title and URL of the page. Use the relative URL for pages in this repo, e.g.
76
74
77
75
```
78
-
- title: Slack Group
79
-
url: slack
76
+
- text: Slack Group
77
+
file: slack.qmd
80
78
```
81
79
82
80
Use the full URL for external pages, e.g.
83
81
84
82
```
85
-
- title: R Developer Page
86
-
url: https://developer.r-project.org/
83
+
- text: R Developer Page
84
+
href: https://developer.r-project.org/
87
85
```
88
86
89
-
Like any change to `config.yml`, you will need to restart the Jekyll server for
90
-
the change to take effect (when previewing locally).
91
-
92
87
## Website theme
93
88
94
-
This is a GitHub pages site, using the [modified minimal Jekyll theme](https://github.com/kbsezginel/gh-pages-template) by [kbsezginel](https://github.com/kbsezginel). The [theme documentation](https://kbsezginel.github.io/gh-pages-template/setup) provides instructions for initial setup and customization, which are probably not required for day-to-day editing.
95
-
96
-
### Jekyll/Liquid notes
97
-
98
-
*`| relative.url` filter will make path relative (add `/` at beginning if necessary)
99
-
*`| absolute.url` filter will add the site domain at the start
100
-
101
-
## Icons
89
+
This is a GitHub pages site, using the R Contributor [brand.yml](https://posit-dev.github.io/brand-yml/) files: `brand-light.yml` and `brand-dark.yml` for light and dark mode respectively.
0 commit comments