Skip to content

Commit aee486e

Browse files
jdutantjdutant
committed
Initializing gh-pages branch
0 parents  commit aee486e

File tree

4 files changed

+196
-0
lines changed

4 files changed

+196
-0
lines changed

‎.github/workflows/publish_docs.yml

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
on:
2+
workflow_dispatch:
3+
push:
4+
branches: main
5+
paths: docs/**
6+
7+
name: Render and publish documentation using Quarto and GitHub pages
8+
9+
jobs:
10+
build-deploy:
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: write
14+
steps:
15+
- name: Check out repository
16+
uses: actions/checkout@v4
17+
18+
- name: Set up Quarto
19+
uses: quarto-dev/quarto-actions/setup@v2
20+
21+
- name: Render and Publish
22+
uses: quarto-dev/quarto-actions/publish@v2
23+
with:
24+
path: docs
25+
target: gh-pages
26+
env:
27+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.gitignore

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Quarto files
2+
/docs/.quarto/
3+
/docs/_output/
4+
5+
# MacOS
6+
.DS_Store

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Julien Dutant
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+142
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Quarto docs template
2+
3+
Set up a new GitHub repository to be documented using [Quarto].
4+
Write your documentation as a Quarto static website in the `docs/` folder. Changes to the documentation are rendered in a separate branch (`gh-pages`) published with GitHub pages.
5+
6+
## Background
7+
8+
An empty repository with Quarto documentation published
9+
as a GitHub Pages websites. Use this template to start
10+
a new project that you want to document using Quarto.
11+
12+
Quarto is a multiformat document generator based on
13+
Pandoc. It can be used as a static website generators
14+
and accepts multiple input formats. You may want to
15+
document your project using Quarto if:
16+
17+
- you want to render your documentation in other formats,
18+
e.g. PDF.
19+
- you need more features than GitHub's wikis or Jekyll,
20+
but not advanced documentation-oriented features of
21+
generators like Sphinx or Docusaurus.
22+
- you're used to write with Quarto.
23+
24+
## Installation
25+
26+
### With "Use this template" on the GitHub website
27+
28+
Click "use this template". Select the option *copy all branches*.
29+
30+
This should work out of the box. If not, try running
31+
`quarto publish gh-pages` within `docs`. (Requires a
32+
local installation of [Quarto].)
33+
34+
### With a pre-existing GitHub repository
35+
36+
Copy from this repository:
37+
38+
- the `docs/` folder, except `_output/` and `.quarto/`. Make sure you include the hidden `.nojekyll` file.
39+
- `.github/workflows/publish_docs.yml`
40+
41+
Add the following lines to a `.gitignore` file at the root
42+
of your repository:
43+
44+
```
45+
# Quarto Documentation artefacts
46+
/docs/_output
47+
/docs/.quarto
48+
```
49+
50+
Run `quarto publish gh-pages` from `docs` in your
51+
repository. This requires a local installation
52+
of Quarto.
53+
54+
## Usage
55+
56+
Write documentation by amending the Quarto website in `docs/`. Changes to this folder that are pushed to the GitHub
57+
repository trigger a new rendering of the documentation.
58+
The output is visible at the URL
59+
`https//<github-owner-name>.github.io/<template-name>`.
60+
Add this URL to your repository's "About" information
61+
on your repository's Github page.
62+
63+
To preview your documentation before pushing it to
64+
GitHub, run `quarto render` in the `docs` website.
65+
Open `docs/_output/index.html` in a browser to
66+
see the result. (This requires a local installation
67+
of [Quarto].)
68+
69+
When you create new documentation pages you need to
70+
list them in `_quarto.yml`:
71+
72+
```yml
73+
navbar:
74+
left:
75+
- href: index.qmd
76+
text: Home
77+
- about.qmd
78+
- new_page.qmd
79+
- folder/new_page.qmd
80+
```
81+
82+
Documentation pages can be written in multiple
83+
formats. See [Quarto guide].
84+
85+
## Advanced usage
86+
87+
### How this works
88+
89+
The GitHub Action that renders and publish your
90+
documentation is configured in
91+
`.github/workflows/publish_docs.yml`. It controls
92+
when the action is triggered and the source
93+
and destination of Quarto rendering. The default
94+
trigger is any pushed change in `docs`, the default
95+
source is `/docs/` on the main branch, the default
96+
destination is the `gh-pages` branch.
97+
98+
Quarto rendering is configured by `docs/_quarto.yml`.
99+
This controls where the output is rendered, which
100+
source files to include in the documentation,
101+
styling the output,
102+
whether to add extra outputs formats such as PDF.
103+
104+
If you change the output folder (`output-dir`),
105+
you need to amend `.gitignore` and the GitHub
106+
Action paramters (`.github/workflows/publish_docs.yml`).
107+
108+
### Make your documentation a Quarto book
109+
110+
If you want to output your documentation as a Quarto
111+
book instead of a Quarto website, you only need
112+
to change the `_quarto.yml` file. Here's an example:
113+
114+
``` yaml
115+
project:
116+
type: book
117+
output-dir: _output
118+
119+
book:
120+
title: "Sample Quarto documentation"
121+
chapters:
122+
- index.qmd
123+
- about.qmd
124+
125+
format:
126+
html:
127+
theme: cosmo
128+
toc: true
129+
pdf:
130+
number-sections: true
131+
```
132+
133+
## Resources
134+
135+
* [Quarto documentation on publishing with GitHub Actions](https://quarto.org/docs/publishing/github-pages.html#github-action).
136+
* [Quarto GitHub Actions] with documentation and examples.
137+
* [GitHub Pages documentation].
138+
139+
[Quarto]: https://quarto.org "Quarto website"
140+
[Quarto guide]: https://quarto.org/docs/guide/ "Quarto guide"
141+
[GitHub Pages]: https://docs.github.com/en/pages "GitHub pages documentation"
142+
[Quarto GitHub Actions]" https://github.com/quarto-dev/quarto-actions "Quarto's team GitHub actions

0 commit comments

Comments
 (0)