From 3acf2b935e91487222612ebfebcc1679c2d297a4 Mon Sep 17 00:00:00 2001 From: gvasquezvargas Date: Mon, 9 Sep 2024 15:06:50 +0200 Subject: [PATCH 1/2] suggestion for style guide, full stop in frontmatter descriptions --- .../community/contributing/styleguide.mdx | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/advocacy_docs/community/contributing/styleguide.mdx b/advocacy_docs/community/contributing/styleguide.mdx index c38351cc472..f76462cc9e9 100644 --- a/advocacy_docs/community/contributing/styleguide.mdx +++ b/advocacy_docs/community/contributing/styleguide.mdx @@ -74,6 +74,7 @@ Included in this guide: * 13 [Dates](#dates) * 14 [Terminology considerations](#terminology-considerations) * 15 [Trademark symbols](#trademark-symbols) +* 16 [Frontmatter](#frontmatter) ## Language and tone @@ -656,4 +657,20 @@ Examples: EDB Postgres® AI, EDB Postgres® Analytics, EDB Postgres® Machine Le For other trademarks, the documentation site already includes a general disclaimer at the footer of every page called "Trademark" which links to https://www.enterprisedb.com/trademarks. Contrary to the specifications on [Trademarks](https://www.enterprisedb.com/trademarks), don't include the symbol in page titles, -because the symbol can affect how search engines index and find pages. \ No newline at end of file +because the symbol can affect how search engines index and find pages. + +## Frontmatter + +The frontmatter is located at the top of every markdown page, and allows you to specify metadata and options in YAML language. Frontmatter lets you control how a page will render. + +Ensure your page, at minimum, includes a `title` and `description` as metadata. It can include other metadata such as `navTitle`, `deepToC`, etc. + +```yaml +--- +title: Working with the Repo +description: Step by step instructions to install and use the docs repo. +--- +``` + +!!!note + Ensure the `description` has a final stop, even if it isn't a full grammatical sentence. Descriptions are used to dynamically build a summary for each section in `index` pages. Since all descriptions are then displayed next to each other, add a full stop to ensure visual consistency. From 40166c9092f65ec334f7d0bc898868f221a7b8ea Mon Sep 17 00:00:00 2001 From: Betsy Gitelman Date: Tue, 24 Sep 2024 11:36:42 -0400 Subject: [PATCH 2/2] Apply suggestions from code review --- advocacy_docs/community/contributing/styleguide.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/advocacy_docs/community/contributing/styleguide.mdx b/advocacy_docs/community/contributing/styleguide.mdx index f76462cc9e9..d6867f9d39b 100644 --- a/advocacy_docs/community/contributing/styleguide.mdx +++ b/advocacy_docs/community/contributing/styleguide.mdx @@ -661,16 +661,16 @@ because the symbol can affect how search engines index and find pages. ## Frontmatter -The frontmatter is located at the top of every markdown page, and allows you to specify metadata and options in YAML language. Frontmatter lets you control how a page will render. +The frontmatter is located at the top of every Markdown page and allows you to specify metadata and options in YAML language. Frontmatter lets you control how a page renders. -Ensure your page, at minimum, includes a `title` and `description` as metadata. It can include other metadata such as `navTitle`, `deepToC`, etc. +Ensure your page, at minimum, includes a `title` and `description` as metadata. It can include other metadata such as `navTitle`, `deepToC`, and so on. ```yaml --- -title: Working with the Repo -description: Step by step instructions to install and use the docs repo. +title: Working with the repo +description: Step-by-step instructions to install and use the docs repo. --- ``` !!!note - Ensure the `description` has a final stop, even if it isn't a full grammatical sentence. Descriptions are used to dynamically build a summary for each section in `index` pages. Since all descriptions are then displayed next to each other, add a full stop to ensure visual consistency. + Ensure the `description` has a final stop (period), even if it isn't a full grammatical sentence. Descriptions are used to dynamically build a summary for each section in `index` pages. Since all descriptions are then displayed next to each other, add a full stop to ensure visual consistency.