From adbc5d1a9d9ba67578d7bea0c2ebbf556cb1007c Mon Sep 17 00:00:00 2001 From: Eric Date: Fri, 6 Mar 2026 13:08:52 -0600 Subject: [PATCH] Handbook: Update article meta tag section (#41059) Closes: https://github.com/fleetdm/fleet/issues/40001 Changes: - Updated the handbook section on article meta tags to document the article categories that we currently use, and the meta tags used by case study articles and comparison articles --- handbook/company/writing.md | 98 ++++++++++++++++++++++++++++++++----- 1 file changed, 87 insertions(+), 11 deletions(-) diff --git a/handbook/company/writing.md b/handbook/company/writing.md index 706f007736..bc8c37dd98 100644 --- a/handbook/company/writing.md +++ b/handbook/company/writing.md @@ -47,23 +47,25 @@ We use `` tags in Markdown articles to set metadata information about the - `authorFullName`: The full name of the author of the article. - `authorGithubUsername`: The Github username of the author. - `category`: The category of the article. determines the article category page the article will be shown on. - > Note: All markdown articles can be found at fleetdm.com/articles + > Note: All markdown articles can be found at [fleetdm.com/blog](/blog) - Supported values: - - `releases` - For Fleet release notes. Articles in this category are available at fleetdm.com/releases - - `security` - For security-related articles. Articles in this category are available at fleetdm.com/securing - - `engineering` - For engineering-related articles. Articles in this category are available at fleetdm.com/engineering - - `success stories` - Articles about how/why Fleet is being used by our customers. Articles in this category are available at fleetdm.com/success-stories - - `announcements` - News and announcements about new features and changes to Fleet. Articles in this category are available at fleeetdm.com/announcements - - `guides` - Non-reference documentation and how-to guides. Articles in this category are available at fleetdm.com/guides - - `podcasts` - Episodes of Fleet's podcast. Articles in this category are available at fleetdm.com/podcasts + - `releases` - For Fleet release notes. Articles in this category are available at [fleetdm.com/releases](/releases) + - `security` - For security-related articles. Articles in this category are available at [fleetdm.com/securing](/securing) + - `engineering` - For engineering-related articles. Articles in this category are available at [fleetdm.com/engineering](/engineering) + - `case study` - Articles about how/why Fleet is being used by our customers. Articles in this category are available at [fleetdm.com/customers](/customers) + - `announcements` - News and announcements about new features and changes to Fleet. Articles in this category are available at [fleeetdm.com/announcements](/announcements) + - `guides` - Non-reference documentation and how-to guides. Articles in this category are available at [fleetdm.com/guides](/guides) + - `podcasts` - Episodes of Fleet's podcast. Articles in this category are available at [fleetdm.com/podcasts](/podcasts) + - `comparison` - Articles that present a comparison between Fleet and a competing product. Articles in this category are only visible in the list of all articles at [fleetdm.com/blog](/blog) + - `articles` - A catch-all category for articles and blog posts that do not fit into other categories. Articles in this category are only visible in the list of all articles at [fleetdm.com/blog](/blog) - `publishedOn`: An ISO 8601 formatted date (YYYY-MM-DD) of the articles publish date. If the article is a guide, this value should be updated whenever a change to the guide is made. - Optional meta tags: - - `articleImageUrl`: A relative link to a cover image for the article. If provided, the image needs to live in the /website/assets/images/articles folder. The image will be added to the card for this article on it's category page, as well as a cover image on the article page. If this value is not provided, the card for the article will display the Fleet logo and the article will have no cover image. - - `description`: A description of the article that will be visible in search results and social share previews. If provided, this value will override the generated meta description for this article. otherwise, the description will default to `[articleTitle] by [authorFullName]`. + - `articleImageUrl`: A relative link to a cover image for the article used for social share previews. If provided, the image needs to live in the /website/assets/images/articles folder. + - `description`: A description of the article that will be visible in search results and social share previews. If provided, this value will override the generated meta description for this article. Otherwise, the description will default to `[articleTitle] by [authorFullName]`. **Example meta tag section:** -```html +``` @@ -73,8 +75,82 @@ We use `` tags in Markdown articles to set metadata information about the ``` +> Note: Some categories of articles will require additional `` tags. +### Case study article meta tags + +Case study articles use a separate article template that requires additional `` tags to populate content outside of the Markdown article. + +- Required `` tags: + - `useBasicArticleTemplate` - Whether or not the case study should use the standard article template or the non-anonymous case study template. **Note:** if this meta tag is set, the case study specific meta tags below are not required. + - `summaryChallenge` - The challenge this case study subject faced before they started using Fleet. Used in the case study summary on the non-anonymous case study template page. + - `summarySolution` - How Fleet helped the case study subject acomplish their goals. Used in the case study summary on the non-anonymous case study template page. + - `summaryKeyResults` - A semicolon-separated list of results that the case study subject saw after using Fleet. Each item in the list is added a bullet point to the case study summary on the non-anonymous case study template page. +- Optional `` tags: + - `companyLogoFilename` - The filename of the case study subject's logo in the `website/assets/images/` folder. **Note:** images for this value are not stored in the articles folder, because they may be used outside of articles (e.g., Testimonial cards on landing pages) + - `quoteContent` - A quote from the case study subject. Used in the quote below the article title on the non-anonymous case study template. + - `quoteAuthorName` - The name of the person quoted for the case study. Used in the quote below the article title on the non-anonymous case study template page. **Note:** this meta tag is required if a `quoteContent` meta tag is set + - `quoteAuthorJobTitle` - The job title of the person quoted for the case study. Used in the quote below the article title on the non-anonymous case study template page. **Note:** this meta tag is required if a `quoteContent` meta tag is set + - `quoteAuthorImageFilename` - The filename of the LinkedIn profile image of the person quoted in the case study. Used in the quote below the article title on the non-anonymous case study template page. Images for this value are not stored in the articles folder, because they may be in used outside of articles (e.g., Testimonial cards on landing pages). **Note:** this meta tag is required if a `quoteContent` meta tag is set. + - `companyName` - The name of the subject of the case study. Used in the "About [companyName]" section on the non-anonymous case study template page. **Note:** This value will only be used if a `companyInfo` meta tag is also set. + - `companyInfo` - A description of the case study subject. Used in the "About [companyName]" section on the non-anonymous case study template page. **Note:** This value will only be used if a `companyName` meta tag is also set. + - `companyInfoLineTwo` - An additional description of the case study subject. Used to add a second paragraph to the "About [companyName]" section on the non-anonymous case study template page. **Note:** This value will only be used if `companyName` and `companyInfo` meta tags are set. + + +**Example case study meta tag section** + +``` + + + + + + + + + + + + + + + + + + + +``` + + + +### Comparison article meta tags + +Comparison articles use a separate article template that requires additional `` tags to populate content outside of the Markdown article. + +- Required `` tags: + - `articleSubtitle` - The text content of the smaller heading that is above the article's title on the comparison article template. Example: "How to choose the right MDM" + - `introductionTextBlockOne` - The introduction paragraph for the comparison. This is a required meta tag because the introduction, article title, and article subtitle are displayed above the Markdown content of comparison articles. + - `articleSlugInCategory` - The URL slug of the comparison article after `fleetdm.com/compare`. i.e., If an article has a `articleSlugInCategory` value set to `jamf`, it will be available at `fleetdm.com/compare/jamf` . +- Optional `` tags: + - `introductionTextBlockTwo` - A optional second introduction paragraph for the comparison. The contents of this meta tag are added as a separate paragraph to the introduction above the Markdown content. + + +**Example comparison article meta tag section** + +``` + + + + + + + + + + +``` + ## Linking to a location on GitHub