jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

Clarify filename and title requirements (#40927)

Browse Source
This commit is contained in:
Ethan Palm
2023-08-27 14:06:59 -07:00
committed by GitHub
parent f89e409aef
commit c5d2e7cb2e
1 changed files with 14 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
content/README.md
View File

@@ -2,9 +2,9 @@
The `/content` directory is where all the site's (English) Markdown content lives! The `/content` directory is where all the site's (English) Markdown content lives!
See the [markup reference guide](/contributing/content-markup-reference.md) for more information about supported Markdown features. See the [markup reference guide](https://docs.github.com/en/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs) for more information about supported Markdown features.
See the [contributing docs](/CONTRIBUTING.md) for general information about working with the docs. See the [contributing docs](https://docs.github.com/en/contributing) for general information about working with the docs.
- [Frontmatter](#frontmatter) - [Frontmatter](#frontmatter)
- [`versions`](#versions) - [`versions`](#versions)
@@ -196,7 +196,7 @@ featuredLinks:
### `allowTitleToDifferFromFilename` ### `allowTitleToDifferFromFilename`
- Purpose: Indicates whether a page is allowed to have a title that differs from its filename. For example, `content/rest/reference/orgs.md` has a title of `Organizations` instead of `Orgs`. Pages with this frontmatter set to `true` will not be flagged in tests or updated by `script/reconcile-ids-with-filenames.js`. - Purpose: Indicates whether a page is allowed to have a title that differs from its filename. Pages with this frontmatter set to `true` will not be flagged in tests or updated by `script/reconcile-ids-with-filenames.js`. Use this value if a file's `title` frontmatter includes Liquid or punctuation that cannot be part of the filename. For example, the article "[About Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users)" uses a Liquid reusable in its title, `'About {% data variables.product.prodname_emus %}'`, which cannot be in the filename, `about-enterprise-managed-users.md`, so the `allowTitleToDifferFromFilename` frontmatter is set to `true`.
- Type: `Boolean`. Default is `false`. - Type: `Boolean`. Default is `false`.
- Optional. - Optional.
@@ -292,16 +292,20 @@ Do not add hardcoded "In this article" sections in the Markdown source or else t
A content file can have **two** types of versioning: A content file can have **two** types of versioning:
* [`versions`](#versions) frontmatter (**required**) - [`versions`](#versions) frontmatter (**required**)
* Determines in which versions the page is available. See [contributing/permalinks](../contributing/permalinks.md) for more info. - Determines in which versions the page is available. See [contributing/permalinks](../contributing/permalinks.md) for more info.
* Liquid statements in content (**optional**) - Liquid statements in content (**optional**)
* Conditionally render content depending on the current version being viewed. See [contributing/liquid-helpers](../contributing/liquid-helpers.md) for more info. Note Liquid conditionals can also appear in `data` and `include` files. - Conditionally render content depending on the current version being viewed. See [contributing/liquid-helpers](../contributing/liquid-helpers.md) for more info. Note Liquid conditionals can also appear in `data` and `include` files.
**Note**: As of early 2021, the `free-pro-team@latest` version is not included URLs. A helper function called `lib/remove-fpt-from-path.js` removes the version from URLs. **Note**: As of early 2021, the `free-pro-team@latest` version is not included URLs. A helper function called `lib/remove-fpt-from-path.js` removes the version from URLs.
## Filenames ## Filenames
When adding a new article, make sure the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the title you use in the article's [`title`](#title) frontmatter. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). A test will flag any discrepancies between title and filename. To override this requirement for a given article, you can add [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) frontmatter. When adding a new article, the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the article's [`title`](#title) frontmatter. For example, the article "[About GitHub CLI](https://docs.github.com/en/github-cli/github-cli/about-github-cli)" has a `title` frontmatter of `About GitHub CLI` and a filename of `about-github-cli.md`.
Directory names for categories and map topics can match the `title` or `shortTitle` frontmatter.
For titles that have punctuation (such as "GitHub's Billing Plans"), you can omit punctuation in filenames (`githubs-billing-plans.md`). For titles that use Liquid variables (such as `About {% data variables.product.prodname_emus %}`), you can use the words that the Liquid renders as in filenames (`about-enterprise-managed-users.md`). A test will flag any discrepancies between title and filename. To override the requirement that titles and filenames match for a given article, you can add [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) in the frontmatter.
## Whitespace control ## Whitespace control
@@ -341,7 +345,7 @@ Links to docs in the `docs-internal` repository must start with a product ID (li
Image paths must start with `/assets` and contain the entire filepath including the file extension. For example, `/assets/images/help/settings/settings-account-delete.png`. Image paths must start with `/assets` and contain the entire filepath including the file extension. For example, `/assets/images/help/settings/settings-account-delete.png`.
The links to Markdown pages undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in [`lib/render-content/plugins/rewrite-local-links`](lib/render-content/plugins/rewrite-local-links.js). The links to Markdown pages undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in [`lib/render-content/plugins/rewrite-local-links`](/lib/render-content/plugins/rewrite-local-links.js).
For example, if you include the following link in a content file: For example, if you include the following link in a content file:
@@ -359,7 +363,7 @@ and when viewed on GitHub Enterprise Server docs, the version is included as wel
### Using AUTOTITLE for internal links ### Using AUTOTITLE for internal links
If you create an internal link, you can use the AUTOTITLE keyword to generate an article's title in the rendered link. See the [markup reference](../contributing/content-markup-reference.md#internal-links-with-autotitle) for details. If you create an internal link, you can use the AUTOTITLE keyword to generate an article's title in the rendered link. See the [markup reference](https://docs.github.com/en/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#internal-links-with-autotitle) for details.
### Linking to the current article in a different version of the docs ### Linking to the current article in a different version of the docs