USWDS-Site - What's new: Add README to posts directory

README.md

@@ -113,9 +113,16 @@ for details). Therefore, be sure to use an actual version tag on all
 `main` branch commits--otherwise a commit hash will show up as the
 version on the production site, which would be confusing.
 
-### Adding content to the "Updates" section
-
-See the [`_posts` directory](_posts/#readme) for instructions on adding updates.
+### Adding content to the "What's new" feed
+
+The [What's new](https://designsystem.digital.gov/about/whats-new/) feed is generated from the files in two directories:
+- `/_posts`: Long format posts generated by [Jekyll posts](https://jekyllrb.com/docs/posts/). These files will automatically generate:
+    - A preview for the news feed
+    - A separate page for the post content
+
+  See the [./_posts/README.md](./_posts/README.md) for instructions on creating a post.
+- `/_posts_short`: Short format previews for the news feed. These files generate only a preview and do _not_ generate a full post page. Use short posts to link to different pages of the site or other locations.
+  - See the [./_posts_short/README.md](./_posts_short/README.md) for instructions on creating a short post.
 
 ### Dynamic content
 

_posts/README.md

@@ -0,0 +1,93 @@
+# Posts
+Posts and [short posts](../_posts_short/README.md) are the two content types that generate the [What's new](../README.md#adding-content-to-the-whats-new-feed) feed.
+
+Posts are long format news posts generated by [Jekyll posts](https://jekyllrb.com/docs/posts/). These files will automatically generate:
+- A preview for the news feed
+- A separate page for the post content
+
+This document provides instructions for [creating a new post](#creating-a-new-post), [customizing a post's metadata](#customizing-post-metadata), and following [post conventions](#post-conventions).
+
+## Creating a new post
+
+1. To create a new post, create a new branch then add a new file to the `/_posts` directory with a filename in the form:
+
+    ```
+    YYYY-MM-DD-title.md
+    ```
+    where:
+    - `YYYY` is the 4-digit year (`2025`) of the publish date
+    - `MM` is the 2-digit month, with a leading zero (`01` for January, `02` for February, etc.)
+    - `DD` is the 2-digit day of the month, also with a leading zero
+    - `title` is the so-called "slug" used in the post URL, and should be all lowercase replace spaces with dashes (e.g. `my-post-title`)
+
+
+    The YYYY-MM-DD date set in the file name will:
+      - Display as the "date" in the post
+      - Sort the post in reverse chronological order (newest items first) in the news feed.
+
+    See the [Jekyll documentation about creating posts](https://jekyllrb.com/docs/posts/#creating-post-files) for more info.
+
+2. Next, in the file's contents, copy and paste the following blank template:
+    ```
+    ---
+    title:
+    category: About
+    author:
+    tags:
+    ---
+
+    An introductory plain text paragraph.
+
+    ## This is an h2 heading
+
+    An ordered list with three items:
+    1. Item one
+    1. Item two
+    1. Item three
+    ```
+    The content inside the triple-dashed lines (`---`) is the post's [front matter](https://jekyllrb.com/docs/front-matter/). You will need to customize the the front matter to define the post's title, author, and more. See the table and code example in the [customizing post metadata](#customizing-post-metadata) section to see the available customization options. 
+
+   Everything below the triple-dashed lines is the content that will appear in the generated post page. Whenever possible, write post content in [Markdown](https://www.markdownguide.org/basic-syntax/). However, HTML is also supported. See the [post conventions](#post-conventions) section below for additional guidance.
+
+## Customizing post metadata
+
+The following table provides reference for the available front matter customization options:
+
+| Key | Description | Required |
+|--------|--------|--------|
+| title | The title of the post | Yes |
+| category | The site category that ties the post to the side navigation. The value for this should always be "About". | Yes|
+| author | The author(s) listed in the byline | No |
+| tags | The tag that describes the category of the post. Multiple tags can be added. | No |
+| excerpt | The post summary that will be included in the post preview | Yes |
+| lead | The first paragraph of your post displayed in large ("lead") text. When present, the lead will be used as the "excerpt" in the post preview. | No |
+| expiration_date | The date when this post will receive the "This content is outdated" alert. This is typically set 2 years from the publication date. | No |
+
+Here is a sample front matter customization:
+
+```md
+---
+title: Lorem ipsum dolor
+category: About
+author: Suzy Q, Jane Doe, and Joe Schmoe
+tags:
+  - discussion
+  - news
+excerpt: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus egestas sed felis eget sodales.
+---
+```
+
+## Post conventions
+
+In general, the following conventions should be followed in your posts:
+
+1. Prefer Markdown files (`.md`) to HTML (`.html`), and remember: You can always embed HTML in Markdown, but not the other way around.
+
+1. When linking to other pages on the site, **always** prefix URIs with the Jekyll base URL (`{{ site.baseurl }}`):
+
+    ```md
+    ## Good
+    Check out [what's new]({{ site.baseurl }}/whats-new/)!
+
+    ## Bad
+    Check out [what's new](/whats-new/)!

_posts_short/README.md

@@ -0,0 +1,77 @@
+# Short posts
+
+Short posts and [posts](../_posts/README.md) and  are the two content types that generate the [What's new](../README.md#adding-content-to-the-whats-new-feed) feed.
+
+Unlike posts, short post files generate only a preview for the news feed and do _not_ generate a full post page. Use short posts to link to different pages of the site or other locations.
+
+This document provides instructions for [creating a new short post](#creating-a-new-short-post) and [customizing a short post's metadata](#customizing-short-post-metadata).
+
+## Creating a new short post
+
+1. To create a new short post, create a new branch then add a new file to this directory (`/_posts_short`) with a filename in the form:
+
+    ```
+    YYYY-MM-DD-title.md
+    ```
+    where:
+    - `YYYY` is the 4-digit year (`2025`) of the publish date
+    - `MM` is the 2-digit month, with a leading zero (`01` for January, `02` for February, etc.)
+    - `DD` is the 2-digit day of the month, also with a leading zero
+    - `title` is the so-called "slug" used in the post URL, and should be all lowercase replace spaces with dashes (e.g. `my-post-title`)
+
+    The YYYY-MM-DD date set in the file name will:
+    - Display as the "date" in the post
+    - Sort the post in reverse chronological order (newest items first) in the news feed.
+
+2. Next, in the file's contents, copy and paste the following blank template:
+    ```
+    ---
+    title:
+    author:
+    tags:
+    excerpt:
+    preview_url:
+    ---
+    ```
+
+    The content inside the triple-dashed lines (`---`) is the post's [front matter](https://jekyllrb.com/docs/front-matter/). You will need to customize the the front matter to define the post's title, author, and more. See the table and code example in the [customizing short post metadata](#customizing-short-post-metadata) section to see the available customization options. 
+
+    Note that for short posts, no other content is needed outside of the page's front matter.
+
+## Customizing short post metadata
+
+The following table provides reference for the available front matter customization options:
+
+| Key | Description | Required |
+|--------|--------|--------|
+| title | The title of the post | Yes |
+| author | The author(s) listed in the byline | No |
+| tags | The tag that describes the category of the post. Multiple tags can be added, but only the first tag will appear above the post title. | Yes |
+| excerpt | The post summary that will be included in the post preview | Yes |
+| preview_url | The url that will be added post preview header link. Add a value of "none" when you want the header to not have a link. | Yes |
+
+Here is a sample implementation of a short post with a related link:
+
+```md
+---
+title: Lorem ipsum dolor
+author: Suzy Q, Jane Doe, and Joe Schmoe
+tags:
+  - Lorem ipsum
+excerpt: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus egestas sed felis eget sodales.
+preview_url: https://github.com/uswds/uswds/discussions/
+---
+```
+
+Here is a sample implementation of a short post without a link:
+
+```md
+---
+title: Lorem ipsum dolor
+author: Suzy Q, Jane Doe, and Joe Schmoe
+tags:
+  - Lorem ipsum
+excerpt: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus egestas sed felis eget sodales.
+preview_url: none
+---
+```