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
Copy file name to clipboardExpand all lines: docs/prerelease/1.5/website-drafts.qmd
+86-69Lines changed: 86 additions & 69 deletions
Original file line number
Diff line number
Diff line change
@@ -4,73 +4,88 @@ title: Website Draft Support
4
4
5
5
{{< include _pre-release-feature.qmd >}}
6
6
7
+
## New in Quarto 1.5
8
+
7
9
This feature improves Quarto's support for draft documents in websites. It does this a few ways:
8
10
9
-
### Improved linking behavior for draft documents
11
+
- Adds the `drafts` option to the `website` key offering new ways to specify drafts: directly in `_quarto.yml`, and via metadata includes and profiles.
10
12
11
-
Previously, draft documents were excluded from search results, listings, and the sitemap. Now, draft documents will not appear in navigation as well (sidebar, navbars, and footers). Entries that link to a draft document will be removed / excluded. In addition, if a page on the website links to a draft document, the link will be omittted (leaving the contents of the link without the hyperlink itself).
13
+
- Introduces the `draft-mode` option to the `website` key to control how drafts are rendered. Drafts can be `gone`, `unlinked` or `visible`.
12
14
13
-
These changes add up to mean that now when you mark a document as a draft, other pages will not link to it, so it will be as if it isn't yet a part of the site.
15
+
- Adds a draft banner to draftpages that are rendered.
14
16
15
-
### Draft Modes
17
+
- Improves the linking behaviour of draft documents. Now, in addition to being excluded from search results, listings, and the sitemap, drafts will not appear in navigation, or be linked from in-text hyperlinks when `draft-mode` is `gone` or `unlinked`.
16
18
17
-
You can use the `draft-mode` option to control the behavior of draft documents in the rendered website. Use the following to control the behavior:
19
+
- Changes the behavior of `quarto preview` for drafts. Drafts will be `visible` in previews regardless of the `draft-mode` setting. In particular, this allows an easier way to preview the appearance of draft content in navigation and listings.
18
20
19
-
-`visible` - the draft will visible and fully available
20
-
-`unlinked` - the draft will be rendered, but will not appear in navigation, search, or listings.
21
-
-`gone` - the draft will have no content and will not be linked to (default).
21
+
Read more about these changes below.
22
22
23
-
When the `gone` mode is selected, each draft document will still produce a file when the site is rendered, but the document will be empty.
23
+
## Website Drafts
24
24
25
-
### Previewing Drafts
25
+
### Specifying Drafts
26
26
27
-
When you use `quarto preview` to preview your local copy of a website, any documents that are marked as drafts will be included in the preview (they will appear throughout the site as they would if they are not previews). When you view a document marked as a draft, a band across the top of the document will notify you that the page is a draft.
27
+
To specify a page or post is a draft, you can add `draft: true` to the document YAML:
28
28
29
-
{.border}
To specify all documents in directory are drafts set `draft: true` in the [directory metadata](/docs/projects/quarto-projects.html#directory-metadata):
32
37
33
-
You can provide a list of prroject relative paths that will be considered a draft in your project configuration using the `drafts` option with an array of paths. Input listed in the option will be considered drafts and treated accodring to the draft mode that is selected.
38
+
```{.yaml filename="posts/_metadata.yml"}
39
+
draft: true
40
+
```
34
41
35
-
Note that you can use `metadata-files` or `profile` to externalize the list of drafts (for example, if you wish to programmatically generate a list of draft documents).
42
+
As an alternative to the `draft` document option, you can also specify the website option `drafts` in `_quarto.yml`:
36
43
37
-
### Complete Example
44
+
```{.yaml filename="_quarto.yml"}
45
+
website:
46
+
title: "Cool Website."
47
+
drafts:
48
+
- posts/post-with-code/index.qmd
49
+
```
38
50
39
-
```{.yaml filename="_quarto.yml"}
40
-
project:
41
-
type: website
51
+
If you would like to specify a list of paths in a separate file, use a [metadata include](/docs/projects/quarto-projects.html#metadata-includes). For example, you could specify your drafts in `drafts.yml`:
52
+
53
+
```{.yaml filename="drafts.yml"}
54
+
website:
55
+
drafts:
56
+
- posts/post-with-code/index.qmd
57
+
```
58
+
59
+
Then, provide this file to `metadata-files`:
42
60
61
+
```{.yaml filename="_quarto.yml"}
43
62
website:
44
63
title: "Cool Website."
45
-
navbar:
46
-
left:
47
-
- stuff/item1.qmd
48
-
- stuff/item2.qmd
49
-
- stuff/item3.qmd
50
-
- listing.qmd
51
-
- text: Another One
52
-
sidebar:
53
-
contents: stuff
54
-
page-footer:
55
-
center:
56
-
- stuff/item1.qmd
57
-
- stuff/item3.qmd
58
-
drafts: # <1>
59
-
- stuff/item3.qmd # <1>
60
-
draft-mode: visible # <2>
61
-
62
-
format:
63
-
html:
64
-
theme: cosmo
65
-
css: styles.css
66
-
toc: true
64
+
65
+
metadata-files:
66
+
- drafts.yml
67
67
```
68
68
69
-
1. The project is providing a simple list of draft documents. The same thing could be specified using `draft: true` in `stuff/item3.qmd`'s front matter.
69
+
You can also set the website `drafts` option using [project profiles](/docs/projects/profiles.html).
70
+
71
+
### Appearance of Drafts
72
+
73
+
You can use the `draft-mode` option to control the content and linking of draft documents in the rendered website.
74
+
The values for `draft-mode` are:
75
+
76
+
-`gone`(default)---Empty and unlinked
77
+
-`unlinked`---Rendered and unlinked
78
+
-`visible`---Rendered and linked
79
+
80
+
A URL will exist for an empty page but the page itself will be blank. Drafts that are rendered will additionally include a draft banner:
70
81
71
-
2. The draft mode is set to `visible`, which will mean that drafts are linked to and visible when the site is rendered.
82
+
{.border fig-alt="Screenshot of a post titled 'Post With Code', displaying a banner at the top of the page titled 'Draft'."}
72
83
73
-
### Complete Example with External Draft List
84
+
When a draft is unlinked it will not appear in search results, listings, the sitemap, or navigation (sidebars, navbars, and footers). If another page links to an unlinked draft document, the link will be omitted leaving the content of the link without the hyperlink itself.
85
+
86
+
As a complete example, consider the following website configuration:
87
+
88
+
:::{#lst-example}
74
89
75
90
```{.yaml filename="_quarto.yml"}
76
91
project:
@@ -82,31 +97,33 @@ website:
82
97
left:
83
98
- stuff/item1.qmd
84
99
- stuff/item2.qmd
85
-
- stuff/item3.qmd
86
-
- listing.qmd
87
-
- text: Another One
88
-
sidebar:
89
-
contents: stuff
90
-
page-footer:
91
-
center:
92
-
- stuff/item1.qmd
93
-
- stuff/item3.qmd
94
-
95
-
format:
96
-
html:
97
-
theme: cosmo
98
-
css: styles.css
99
-
toc: true
100
-
101
-
metadata-files: # <1>
102
-
- drafts.yml # <1>
100
+
drafts: # <1>
101
+
- stuff/item2.qmd # <1>
102
+
draft-mode: unlinked # <2>
103
103
```
104
104
105
-
1.This project includes a metadata file which controls the `draft` behavior. This could be useful (for example) when a `pre-render` script would like to generate a file which contains a list of draft documents in the project.
105
+
1.The project is providing a simple list of draft documents. The same thing could be specified using `draft: true` in `stuff/item2.qmd`'s front matter.
106
106
107
-
```{.yaml filename="drafts.yml"}
108
-
website:
109
-
drafts:
110
-
- stuff/item3.qmd
111
-
draft-mode: gone
112
-
```
107
+
2. The draft mode is set to `unlinked`, so drafts are rendered but not linked to.
108
+
109
+
A complete `_quarto.yml` example
110
+
111
+
:::
112
+
113
+
When rendered the navbar in the above site will omit the item for `stuff/item2.qmd`:
114
+
115
+
{.border fig-alt="Navigation bar for a site with title 'Cool Website.' showing a single navigation item 'Item 1'."}
116
+
117
+
However, `stuff/item2.qmd` is still available at `stuff/item2.html` and shows the draft banner:
118
+
119
+
{.border fig-alt="Screenshot of a webpage with title 'Item 2'. The navigation bar shows a single navigation item 'Item 1'. Above the navigation bar is a banner with the text 'Draft'."}
120
+
121
+
### Previewing Drafts
122
+
123
+
Regardless of the `draft-mode` setting, when you preview a site with `quarto preview` drafts will be `visible`.
124
+
Draft pages will be rendered and display a draft banner, and any links or navigation items pointing at the draft pages will be visible and active.
125
+
For example, when the site described in @lst-example, is previewed a link to `stuff/item2.html` appears in the navigation:
126
+
127
+
{.border fig-alt="Screenshot of a webpage with title 'Item 2'. The navigation bar shows two navigation items 'Item 1' and 'Item 2'. Above the navigation bar is a banner with the text 'Draft'."}
128
+
129
+
This preview behaviour includes previews generated with the **Render** button in RStudio, and the **Preview** button in VS Code.
0 commit comments