Implement support for draft pages (#2392)

* feat: support draft pages

* implemented support for draft pages
* added integration test
* updated relevant documentation (english only)

* docs: explicitly mention "markdown draft pages"

* chore: add changeset

* chore: modify changeset

- changed type to 'patch'
- added more description

2 files changed, 31 insertions, 1 deletions

diff --git a/docs/src/pages/en/guides/markdown-content.md b/docs/src/pages/en/guides/markdown-content.md
index da4e38985..85d9b9ed8 100644
--- a/docs/src/pages/en/guides/markdown-content.md
+++ b/docs/src/pages/en/guides/markdown-content.md
@@ -98,6 +98,7 @@ Markdown pages have a special frontmatter property for `layout`. This defines th
 # src/pages/index.md
 layout: ../../layouts/BaseLayout.astro
 title: My cool page
+draft: false
 ---
 
 # Hello World!
@@ -128,6 +129,7 @@ For Markdown files, the `content` prop also has an `astro` property which holds
   "date": "Tuesday, July 27 2021",
   "author": "Matthew Phillips",
   "description": "Astro 0.18 is our biggest release since Astro launch.",
+  "draft": false,
   **/
   "astro": {
     "headers": [
@@ -159,6 +161,34 @@ Using images or videos follows Astro's normal import rules:
   - Example: Image is located at `/public/assets/img/astonaut.png` → Markdown: `![Astronaut](assets/img/astronaut.png)`
 - Or use `import` as explained on the [imports page](/en/guides/imports#other-assets) (when using Astro's Markdown Component)
 
+### Markdown draft pages
+
+Markdown pages which have the property `draft` set in their frontmatter are referred to as "draft pages". By default, Astro excludes these pages from the build when building the static version of your page (i.e `astro build`), which means that you can exclude draft/incomplete pages from the production build by setting `draft` to `true`. To enable building of draft pages, you can set `buildOptions.drafts` to `true` in the configuration file, or pass the `--drafts` flag when running `astro build`. Markdown pages which do not have the `draft` property set are not affected. An example of a markdown draft page can be:
+
+```markdown
+---
+# src/pages/blog-post.md
+title: My Blog Post
+draft: true
+---
+
+This is my blog post which is currently incomplete.
+```
+
+An example of a markdown post which is not a draft:
+
+```markdown
+---
+# src/pages/blog-post.md
+title: My Blog Post
+draft: false
+---
+
+This is my blog post...
+```
+
+> This feature only applies to local markdown pages, not the `<Markdown />` component, or remote markdown.
+
 ## Astro's Markdown Component
 
 Astro has a dedicated component used to let you render your markdown as HTML components. This is a special component that is only exposed to `.astro` files. To use the `<Markdown>` component, within your frontmatter block use the following import statement:
diff --git a/docs/src/pages/en/reference/configuration-reference.md b/docs/src/pages/en/reference/configuration-reference.md
index 7d6cb37e9..82c535a65 100644
--- a/docs/src/pages/en/reference/configuration-reference.md
+++ b/docs/src/pages/en/reference/configuration-reference.md
@@ -61,7 +61,7 @@ The `renderers` option defines the framework renderers to be used by Astro.
 
 #### buildOptions
 
-The `buildOptions` option configures how a site is built, including its base URL (`buildOptions.site`), whether it includes a sitemap (`buildOptions.sitemap`), and whether its pages should be files (`path.html`) or directories (`path/index.html`) (`buildOptions.pageUrlFormat`).
+The `buildOptions` option configures how a site is built, including its base URL (`buildOptions.site`), whether it includes a sitemap (`buildOptions.sitemap`), whether markdown draft pages should be included in the build (`buildOptions.drafts`), and whether its pages should be files (`path.html`) or directories (`path/index.html`) (`buildOptions.pageUrlFormat`).
 
 #### devOptions