pulumi · jkodroff · Jul 7, 2025
diff --git a/BLOGGING.md b/BLOGGING.md
@@ -111,7 +111,7 @@ including all the required frontmatter parameters.
 
 Posts are written in [Markdown](https://daringfireball.net/projects/markdown/) and rendered with [BlackFriday](https://github.com/russross/blackfriday), Hugo's default Markdown processor. GitHub's [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) guide is a helpful syntax reference if you need it. You can also include HTML in your posts, if you need greater control over the output than Markdown can provide.
 
-For formatting guidelines, see the Style Guide in [CONTRIBUTING.md](CONTRIBUTING.md#style-guide).
+For formatting guidelines, see [the Style Guide](./STYLE-GUIDE.md).
 
 ### Code Blocks
 
@@ -126,22 +126,6 @@ let bucket = new aws.s3.BucketV2("stuff");
 
 [Additional languages are available](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) as well.
 
-### Notes
-
-Shortcode for a warning note:
-
-```
-> [!WARNING]
-> **DANGER** Will Robinson!
-```
-
-Shortcode for an info note:
-
-```
-> [!INFO]
-> Using Bastion hosts is a best practice.
-```
-
 ### Media
 
 #### Inline Images
@@ -173,16 +157,16 @@ To use Pulumi's primary brand font Gilroy in your `meta_image`, first [download
 
 A few things to keep in mind when designing a `meta image`:
 
-   - Avoid placing important text or graphic elements too close to the edges of the frame — elements at the edges may get cropped at some display ratios
-   - Try to include at least one Pulumi identifier (word mark, Pulumipus) so viewers can tell at a glance that the image belongs to the Pulumi blog
-   - Use dark text on light backgrounds, and light text on dark backgrounds to ensure readability
-   - Remember to zoom out from your image and confirm it looks as you intend at a thumbnail size
+- Avoid placing important text or graphic elements too close to the edges of the frame — elements at the edges may get cropped at some display ratios
+- Try to include at least one Pulumi identifier (word mark, Pulumipus) so viewers can tell at a glance that the image belongs to the Pulumi blog
+- Use dark text on light backgrounds, and light text on dark backgrounds to ensure readability
+- Remember to zoom out from your image and confirm it looks as you intend at a thumbnail size
 
 #### Video
 
 To embed a YouTube video, you can use Hugo's built-in [`youtube` shortcode](https://gohugo.io/content-management/shortcodes/#youtube), which takes the video's YouTube ID, obtainable from its public URL on youtube.com:
 
-```
+```plain
 {{< youtube "kDB-YRKFfYE?rel=0" >}}
 ```
 
@@ -209,10 +193,9 @@ After your Pull Request is approved, but before merge/publication date, reach ou
 
 Because the website is deployed in response to a commit to pulumi/docs `master`, it isn't possible to schedule a post to be released automatically at a precise date and time. (The `date` frontmatter property is used only for sorting and display purposes; it has no effect on whether or when a post gets published.) You can, however, influence the timing of the publishing process manually. See the [Merging and Releasing section of the README](README.md#merging-and-releasing) for details.
 
-## Publishing Check List
+## Publishing Checklist
 
 - [ ] As mentioned, use the Hugo blog-post generator instead of copying another post: `make new-blog-post` (or alternatively, the more verbose but equivalent `hugo new --kind blog-post "content/blog/[your-slug]"`)
-- [ ] Spell and grammar check. Consider using a service such as [Grammarly](http://grammarly.com).
 - [ ] Check for a break `<!--more-->` after the first paragraph, and ensure that your post's introduction looks right on the blog home page.
 - [ ] Check that your meta_image appears properly on the blog home page. Do not use animated GIFs for preview images.
 - [ ] Check that your meta_image is using the current logos for Pulumi and others.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,86 +1,43 @@
 # Contributing Pulumi Documentation
 
-## Pulumi terminology
-
-- Use `pulumi` or "the Pulumi CLI" to refer to the CLI.
-- Use `pulumi.com` to refer to the service.
-
 ## Documentation structure
 
-- There is a folder for each heading in the top navigation, such as `Install`, `getting-started`, etc.
+The mapping from documentation page to section and table-of-contents (TOC) is stored largely in each page's front matter, leveraging [Hugo Menus](https://gohugo.io/content-management/menus/). Menus for the CLI commands and API reference are specified in `./config.toml`.
 
-- The mapping from documentation page to section and table-of-contents (TOC) is stored largely in each page's front matter, leveraging [Hugo Menus](https://gohugo.io/content-management/menus/). Menus for the CLI commands and API reference are specified in `./config.toml`.
+## Hugo tips
 
-### Links to other files
+### Short codes
 
-We generally use Hugo's [`relref` shortcode](https://gohugo.io/content-management/shortcodes/#ref-and-relref) when linking to other pages. Examples:
+To share common content across articles, use [Hugo Shortcodes](https://gohugo.io/content-management/shortcodes/). Place a .html file in the [layouts/shortcodes] folder. To include it in a page, use syntax `{{< my-shortcode >}}`
 
-```markdown
-[Install]({{< relref "/docs/get-started/install" >}})
-[Outputs]({{< relref "/docs/intro/concepts/stack#outputs" >}})
-```
+For example, our custom [`cleanup`](layouts/shortcodes/cleanup.html) shortcode can be included in .md files, to include common text about cleaning up stack resources:
 
-Which, on a page inside the `./content/reference` directory, will generate:
-
-```html
-<a href="/docs/install/">Install</a>
-<a href="/docs/intro/concepts/stack/#stack-outputs">Outputs</a>
+```plain
+{{< cleanup >}}
 ```
 
-### Hugo tips
-
-- **Redirects.** If you rename a file or directory, add a 301 redirect in the front-matter via an [alias](https://gohugo.io/content-management/urls/#aliases) `aliases: [/previous-dir/previousfile.html]`.
-
-- **Includes.**
-
-  - **.md files.** To share common content across articles, use [Hugo Shortcodes](https://gohugo.io/content-management/shortcodes/). Place a .html file in the [layouts/shortcodes] folder. To include it in a page, use syntax `{{< my-shortcode >}}`
-
-    For example, our custom [`cleanup`](layouts/shortcodes/cleanup.html) shortcode can be included in .md files, to include common text about cleaning up stack resources:
-
-    ```md
-    {{< cleanup >}}
-    ```
+HTML layouts can include other layouts inside the [layouts/partials](layouts/partials) directory, e.g.:
 
-  - **.html layout files.** HTML layouts can include other layouts inside the [layouts/partials](layouts/partials) directory, e.g.:
-
-    ```html
-    {{ partial "head.html" . }}
-    ```
-
-- **Front-matter variables.** You can define a front-matter variable in the YAML section at the top of a file. For instance, the you could add the following front matter `foo: "bar"`, and then reference the variable in markdown with the syntax `{{< param foo >}}`.
-
-  - **no_on_this_page** Specify this variable to prevent displaying an "On This Page" TOC on the right nav for the page.
-  - **block_external_search_index** Specify this variable to prevent crawlers from indexing the page.
-## Style guide
-
-### Language and terminology styles
-
-- Top level headings use **Title Case**, where each word starts with a capital letter.
-- All other headings use **Sentence case**, where only the first word and any proper nouns have a capital letter.
-- Use capitalization only for a proper noun, and use throughout. For example, "stack" should almost always be lowercase in text.
-
-### Referring to "things"
-
-- References to the Pulumi CLI or CLI commands should be enclosed in backticks (e.g., `pulumi up`).
-- References to UI elements within a webpage should be **bold**. (e.g., "Go to the **Account** page in the Pulumi Console and select **sync profile with GitHub**").
-- Use arrows to indicate a navigation. (e.g., "Go to **FooPage** &gt; **BarItem**").
-
-### Formatting
+```plain
+{{ partial "head.html" . }}
+```
 
-- Use hash marks for headings (`#`, `##`, etc)
-- Use double-asterisks for bold `**`
-- Use underscore for italic `_`
-- Use `--` for en dashes and `---` for em dashes
-  - Do not put spaces before or after the dashes
-- Use code fences (triple-backticks) and a [language identifier](https://gohugo.io/content-management/syntax-highlighting/) for code formatting and syntax highlighting:
-  <pre><code>```typescript
-  const foo = "bar";
-  ```</code></pre>
+### Front matter
 
-### Sections
+Front matter is defined as a YAML block at the top of a Markdown document that defines metadata about the page. Pulumi docs pages often include the following front matter variables:
 
-If a tutorial has more following tutorials, use a **Next steps** section at the end. If you're linking to other reference material, use **Learn more**.
+- `aliases`: A list of relative URLs that should point to the content in this page. When moving or renaming a page, you must add an `alias` entry for the old path of the page relative to the `content/` folder.
+- `allow_long_title`: Set to `true` in order disable length validation on the `title` attribute.
+- `block_external_search_index`: Set to `true` to prevent crawlers from indexing the page.
+- `h1`: If specified, the `<h1>` at the top of the page will use this value instead of the value in the `title` attribute.
+- `menu`: Specifies where a page appears in the document navigation tree.
+- `meta_desc`: Required (unless `redirect_to` is set), at least 50 characters, no longer than 160 characters. This displays as the description of the page in web search results.
+- `meta_image`: Blog posts only. Relative path to an image to display on the blog post list page and for social media previews. The image must be a PNG file for compatibility.
+- `meta_title`: If specified, the meta title (for OpenGraph) will use this value instead of the value in the `title` attribute.
+- `redirect_to`: The relative or absolute URL of a permanent redirect.
+- `title`: Required (unless `redirect_to` is set), 60 characters or less. This controls the default value for the `<title>` tag as well at the top level `<h1>` in the document.
+- `title_tag`: If specified, the `<title>` tag on the rendered call will use this value instead of the `title` attribute.
 
-## Blog Post Authoring
+You can also define arbitrary front-matter variable in the YAML section at the top of a file and refer to that same value in the page content. For instance, the you could add the following front matter `foo: "bar"`, and then reference the variable in markdown with the syntax `{{< param foo >}}`.
 
-For instructions on contributing to the [Pulumi blog](https://www.pulumi.com/blog/), [see BLOGGING.md](BLOGGING.md).
+For more information, see [Front Matter](https://gohugo.io/content-management/front-matter/) in the Hugo docs.
diff --git a/README.md b/README.md
@@ -13,13 +13,13 @@
 
 ## Table of contents
 
-- :blue_book: [View Pulumi Docs](https://pulumi.com/docs/?utm_campaign=pulumi-docs-github-repo&utm_source=github.com&utm_medium=docs-toc)
-- :clap: [Contributing](#Contributing)
-- :toolbox:	[Setup and Development](#setup-and-development)
-  - [Generating SDK and CLI documentation](#generating-sdk-and-cli-documentation)
-- :busts_in_silhouette: [Pulumi Community](#community)
-- :blue_book: [Pulumi Developer Resources](#pulumi-resources)
-- :compass:	[Pulumi Roadmap](#pulumi-roadmap)
+* :blue_book: [View Pulumi Docs](https://pulumi.com/docs/?utm_campaign=pulumi-docs-github-repo&utm_source=github.com&utm_medium=docs-toc)
+* :clap: [Contributing](#Contributing)
+* :toolbox:	[Setup and Development](#setup-and-development)
+  * [Generating SDK and CLI documentation](#generating-sdk-and-cli-documentation)
+* :busts_in_silhouette: [Pulumi Community](#community)
+* :blue_book: [Pulumi Developer Resources](#pulumi-resources)
+* :compass:	[Pulumi Roadmap](#pulumi-roadmap)
 
 ## About this repository
 
@@ -75,7 +75,7 @@ The `Makefile` exposes a number of useful helpers for authoring:
 * `make ensure` resolves and installs all dependencies
 * `make lint` checks all Markdown files for correctness
 * `make format` formats all applicable files to ensure they conform to style guidelines
-* `make serve` runs the Hugo server locally at http://localhost:1313 and watches for changes. You can set `BUILD_FUTURE=false` to simulate production behavior by excluding future-dated content (e.g., `BUILD_FUTURE=false make serve`)
+* `make serve` runs the Hugo server locally at <http://localhost:1313> and watches for changes. You can set `BUILD_FUTURE=false` to simulate production behavior by excluding future-dated content (e.g., `BUILD_FUTURE=false make serve`)
 * `make serve-all` does the same as `make serve`, but also watches for changes to CSS and JS source files
 * `make build` generates the website and writes it to `./public`
 * `make build-assets` builds only the CSS and JavaScript asset bundles