USWDS-Site - What's new: Add README to posts directory #3047
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/)! | ||
|
Contributor
There was a problem hiding this comment. If we're repeating documentation, perhaps the general README is the best place for it. Folder specific guidance should live here.
Contributor
Author
There was a problem hiding this comment. I moved some of the content into the repo's main README in 6fc6de4. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| --- | ||
| ``` |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
polish: This section could be moved up as part of the frontmatter example.