Merge pull request #1061 from quarto-dev/website-drafts

Improve website drafts docs

docs/prerelease/1.5/website-drafts.qmd

@@ -4,73 +4,88 @@ title: Website Draft Support
 
 {{< include _pre-release-feature.qmd >}}
 
+## New in Quarto 1.5
+
 This feature improves Quarto's support for draft documents in websites. It does this a few ways:
 
-### Improved linking behavior for draft documents
+-   Adds the `drafts` option to the `website` key offering new ways to specify drafts: directly in `_quarto.yml`, and via metadata includes and profiles.
 
-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).
+-   Introduces the `draft-mode` option to the `website` key to control how drafts are rendered. Drafts can be `gone`, `unlinked` or `visible`.
 
-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.
+-   Adds a draft banner to draft pages that are rendered.
 
-### Draft Modes
+-   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`. 
 
-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:
+-   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. 
 
--   `visible` - the draft will visible and fully available
--   `unlinked` - the draft will be rendered, but will not appear in navigation, search, or listings.
--   `gone` - the draft will have no content and will not be linked to (default).
+Read more about these changes below. 
 
-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.
+## Website Drafts
 
-### Previewing Drafts
+### Specifying Drafts
 
-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.
+To specify a page or post is a draft, you can add `draft: true` to the document YAML:
 
-![Previewing a draft document](draft-preview.png){.border}
+``` {.yaml filename="posts/post-with-code/index.qmd"}
+---
+title: "Post with Code"
+draft: true
+---
+```
 
-### Website Project Drafts
+To specify all documents in directory are drafts set `draft: true` in the [directory metadata](/docs/projects/quarto-projects.html#directory-metadata): 
 
-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.
+``` {.yaml filename="posts/_metadata.yml"}
+draft: true
+```
 
-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).
+As an alternative to the `draft` document option, you can also specify the website option `drafts` in `_quarto.yml`:
 
-### Complete Example
+``` {.yaml filename="_quarto.yml"}
+website:
+  title: "Cool Website."
+  drafts:
+    - posts/post-with-code/index.qmd
+```
 
-```{.yaml filename="_quarto.yml"}
-project:
-  type: website
+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`:
+
+``` {.yaml filename="drafts.yml"}
+website:
+  drafts:
+    - posts/post-with-code/index.qmd
+```
+
+Then, provide this file to `metadata-files`:
 
+``` {.yaml filename="_quarto.yml"}
 website:
   title: "Cool Website."
-  navbar:
-    left:
-      - stuff/item1.qmd
-      - stuff/item2.qmd
-      - stuff/item3.qmd
-      - listing.qmd
-      - text: Another One
-  sidebar:
-    contents: stuff
-  page-footer: 
-    center: 
-      - stuff/item1.qmd
-      - stuff/item3.qmd
-  drafts:                   # <1>
-    - stuff/item3.qmd       # <1>
-  draft-mode: visible       # <2>
-
-format:
-  html:
-    theme: cosmo
-    css: styles.css
-    toc: true
+
+metadata-files:
+  - drafts.yml
 ```
 
-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.
+You can also set the website `drafts` option using [project profiles](/docs/projects/profiles.html).
+
+### Appearance of Drafts
+
+You can use the `draft-mode` option to control the content and linking of draft documents in the rendered website. 
+The values for `draft-mode` are:
+
+-   `gone`(default)---Empty and unlinked
+-   `unlinked`---Rendered and unlinked
+-   `visible`---Rendered and linked
+
+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:
 
-2. The draft mode is set to `visible`, which will mean that drafts are linked to and visible when the site is rendered. 
+![A rendered draft document will include a "Draft" banner](images/website-drafts-banner.png){.border fig-alt="Screenshot of a post titled 'Post With Code', displaying a banner at the top of the page titled 'Draft'."}
 
-### Complete Example with External Draft List
+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.
+
+As a complete example, consider the following website configuration:
+
+:::{#lst-example}
 
 ```{.yaml filename="_quarto.yml"}
 project:
@@ -82,31 +97,33 @@ website:
     left:
       - stuff/item1.qmd
       - stuff/item2.qmd
-      - stuff/item3.qmd
-      - listing.qmd
-      - text: Another One
-  sidebar:
-    contents: stuff
-  page-footer: 
-    center: 
-      - stuff/item1.qmd
-      - stuff/item3.qmd
-
-format:
-  html:
-    theme: cosmo
-    css: styles.css
-    toc: true
-  
-metadata-files:  # <1>
-  - drafts.yml   # <1>
+  drafts:                   # <1>
+    - stuff/item2.qmd       # <1>
+  draft-mode: unlinked      # <2>
 ```
 
-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.
+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.
 
-```{.yaml filename="drafts.yml"}
-website:
-  drafts:
-    - stuff/item3.qmd
-  draft-mode: gone
-```
+2. The draft mode is set to `unlinked`, so drafts are rendered but not linked to. 
+
+A complete `_quarto.yml` example
+
+:::
+
+When rendered the navbar in the above site will omit the item for `stuff/item2.qmd`:
+
+![](images/website-drafts-nav.png){.border fig-alt="Navigation bar for a site with title 'Cool Website.' showing a single navigation item 'Item 1'."}
+
+However, `stuff/item2.qmd` is still available at `stuff/item2.html` and shows the draft banner:
+
+![](images/website-drafts-item2.png){.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'."}
+
+### Previewing Drafts
+
+Regardless of the `draft-mode` setting, when you preview a site with `quarto preview` drafts will be `visible`. 
+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. 
+For example, when the site described in @lst-example, is previewed a link to `stuff/item2.html` appears in the navigation:
+
+![](images/website-drafts-preview.png){.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'."}
+
+This preview behaviour includes previews generated with the **Render** button in RStudio, and the **Preview** button in VS Code.