Merge pull request #39721 from github/repo-sync

Repo sync

Author: docs-bot

content/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors.md

@@ -17,6 +17,11 @@ shortTitle: Contributor guidelines
 
 To help your project contributors do good work, you can add a file with contribution guidelines to your project repository's root, `docs`, or `.github` folder. When someone opens a pull request or creates an issue, they will see a link to that file. {% ifversion fpt or ghec %}The link to the contributing guidelines also appears on your repository's `contribute` page. For an example of a `contribute` page, see [github/docs/contribute](https://github.com/github/docs/contribute).{% endif %}
 
+{% ifversion fpt or ghec or ghes > 3.18 %}If your repository includes a `CONTRIBUTING.md` file, {% data variables.product.github %} also surfaces it in two other places to make it easier for contributors to discover:
+
+* A "{% octicon "people" aria-hidden="true" aria-label="people" %} Contributing" tab in the repository overview (next to the "{% octicon "book" aria-hidden="true" aria-label="book" %} README" and "{% octicon "code-of-conduct" aria-hidden="true" aria-label="code-of-conduct" %} Code of conduct")
+* A "Contributing" link in the repository sidebar{% endif %}
+
 For the repository owner, contribution guidelines are a way to communicate how people should contribute.
 
 For contributors, the guidelines help them verify that they're submitting well-formed pull requests and opening useful issues.
@@ -28,7 +33,7 @@ You can create default contribution guidelines for your organization or personal
 > [!TIP]
 > Repository maintainers can set specific guidelines for issues by creating an issue or pull request template for the repository. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates).
 
-## Adding a _CONTRIBUTING_ file
+## Adding a `CONTRIBUTING.md` file
 
 {% data reusables.repositories.navigate-to-repo %}
 {% data reusables.files.add-file %}

data/ui.yml

@@ -260,6 +260,17 @@ footer:
   expert_services: Expert services
   blog: Blog
   machine: Some of this content may be machine- or AI-translated.
+bespoke_landing:
+  articles: Articles
+  all_categories: All categories
+  search_articles: Search articles
+discovery_landing:
+  recommended: Recommended
+  articles: Articles
+  all_categories: All categories
+  search_articles: Search articles
+journey_landing:
+  articles: '{{ number }} Articles'
 product_landing:
   quickstart: Quickstart
   reference: Reference

src/fixtures/fixtures/data/ui.yml

@@ -260,6 +260,17 @@ footer:
   expert_services: Expert services
   blog: Blog
   machine: Some of this content may be machine- or AI-translated.
+bespoke_landing:
+  articles: Articles
+  all_categories: All categories
+  search_articles: Search articles
+discovery_landing:
+  recommended: Recommended
+  articles: Articles
+  all_categories: All categories
+  search_articles: Search articles
+journey_landing:
+  articles: '{{ number }} Articles'
 product_landing:
   quickstart: Quickstart
   reference: Reference

src/frame/components/ui/ScrollButton/ScrollButton.tsx

@@ -18,6 +18,14 @@ export const ScrollButton = ({ className, ariaLabel }: ScrollButtonPropsT) => {
     // We cannot determine document.documentElement.scrollTop height because we set the height: 100vh and set overflow to auto to keep the header sticky
     // That means window.scrollTop height is always 0
     // Using IntersectionObserver we can determine if the h1 header is in view or not. If not, we show the scroll to top button, if so, we hide it
+    const h1Element = document.getElementsByTagName('h1')[0]
+    if (!h1Element) {
+      if (process.env.NODE_ENV !== 'production') {
+        throw new Error('No h1 element found in the document.')
+      }
+      return
+    }
+
     const observer = new IntersectionObserver(
       function (entries) {
         if (entries[0].isIntersecting === false) {
@@ -28,7 +36,7 @@ export const ScrollButton = ({ className, ariaLabel }: ScrollButtonPropsT) => {
       },
       { threshold: [0] },
     )
-    observer.observe(document.getElementsByTagName('h1')[0])
+    observer.observe(h1Element)
     return () => {
       observer.disconnect()
     }

src/frame/lib/frontmatter.js

@@ -14,6 +14,9 @@ const layoutNames = [
   'release-notes',
   'inline',
   'category-landing',
+  'bespoke-landing',
+  'discovery-landing',
+  'journey-landing',
   false,
 ]
 
@@ -325,6 +328,11 @@ export const schema = {
       },
       description: 'Array of articles to feature in the spotlight section',
     },
+    // Recommended configuration for category landing pages
+    recommended: {
+      type: 'array',
+      description: 'Array of articles to feature in the carousel section',
+    },
   },
 }
 

src/frame/middleware/context/generic-toc.ts

@@ -3,15 +3,34 @@ import type { Response, NextFunction } from 'express'
 import type { ExtendedRequest, Context, Tree, ToC } from '@/types'
 import findPageInSiteTree from '@/frame/lib/find-page-in-site-tree'
 
+function isNewLandingPage(currentLayoutName: string): boolean {
+  return (
+    currentLayoutName === 'category-landing' ||
+    currentLayoutName === 'bespoke_landing' ||
+    currentLayoutName === 'discovery_landing' ||
+    currentLayoutName === 'journey_landing'
+  )
+}
+
+// TODO: TEMP: This is a temporary solution to turn off/on new landing pages while we develop them.
+function isNewLandingPageFeature(req: ExtendedRequest): boolean {
+  return (
+    req.query?.feature === 'bespoke-landing' ||
+    req.query?.feature === 'journey-landing' ||
+    req.query?.feature === 'discovery-landing'
+  )
+}
+
 // This module adds either flatTocItems or nestedTocItems to the context object for
 // product, category, and subcategory TOCs that don't have other layouts specified.
 // They are rendered by includes/generic-toc-flat.html or includes/generic-toc-nested.html.
 export default async function genericToc(req: ExtendedRequest, res: Response, next: NextFunction) {
   if (!req.context) throw new Error('request not contextualized')
   if (!req.context.page) return next()
   if (
+    !isNewLandingPageFeature(req) &&
     req.context.currentLayoutName !== 'default' &&
-    req.context.currentLayoutName !== 'category-landing'
+    !isNewLandingPage(req.context.currentLayoutName || '')
   )
     return next()
   // This middleware can only run on product, category, and subcategories.
@@ -96,7 +115,10 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
     renderIntros = false
     req.context.genericTocNested = await getTocItems(treePage, req.context, {
       recurse: isRecursive,
-      renderIntros: req.context.currentLayoutName === 'category-landing' ? true : false,
+      renderIntros:
+        isNewLandingPageFeature(req) || isNewLandingPage(req.context.currentLayoutName || '')
+          ? true
+          : false,
       includeHidden,
     })
   }

src/landings/components/bespoke/BespokeLanding.tsx

@@ -0,0 +1,29 @@
+import { useMemo } from 'react'
+
+import { DefaultLayout } from '@/frame/components/DefaultLayout'
+import { useBespokeContext } from '@/landings/context/BespokeContext'
+import { LandingHero } from '@/landings/components/shared/LandingHero'
+import { ArticleGrid } from '@/landings/components/shared/LandingArticleGridWithFilter'
+
+import type { ArticleCardItems } from '@/landings/types'
+
+export const BespokeLanding = () => {
+  const { title, intro, tocItems } = useBespokeContext()
+
+  const flatArticles: ArticleCardItems = useMemo(
+    () => tocItems.flatMap((item) => item.childTocItems || []),
+    [tocItems],
+  )
+
+  return (
+    <DefaultLayout>
+      <div data-search="article-body">
+        <LandingHero title={title} intro={intro} />
+
+        <div data-search="hide">
+          <ArticleGrid flatArticles={flatArticles} />
+        </div>
+      </div>
+    </DefaultLayout>
+  )
+}

src/landings/components/discovery/DiscoveryLanding.tsx

@@ -0,0 +1,28 @@
+import { useMemo } from 'react'
+
+import { DefaultLayout } from '@/frame/components/DefaultLayout'
+import { useDiscoveryContext } from '@/landings/context/DiscoveryContext'
+import { LandingHero } from '@/landings/components/shared/LandingHero'
+import { ArticleGrid } from '@/landings/components/shared/LandingArticleGridWithFilter'
+import { LandingCarousel } from '@/landings/components/shared/LandingCarousel'
+
+import type { ArticleCardItems } from '@/landings/types'
+
+export const DiscoveryLanding = () => {
+  const { title, intro, tocItems, recommended } = useDiscoveryContext()
+
+  const flatArticles: ArticleCardItems = useMemo(
+    () => tocItems.flatMap((item) => item.childTocItems || []),
+    [tocItems],
+  )
+
+  return (
+    <DefaultLayout>
+      <div>
+        <LandingHero title={title} intro={intro} />
+        <LandingCarousel flatArticles={flatArticles} recommended={recommended} />
+        <ArticleGrid flatArticles={flatArticles} />
+      </div>
+    </DefaultLayout>
+  )
+}

src/landings/components/journey/JourneyLanding.tsx

@@ -0,0 +1,17 @@
+import { DefaultLayout } from '@/frame/components/DefaultLayout'
+import { useJourneyContext } from '@/landings/context/JourneyContext'
+import { LandingHero } from '@/landings/components/shared/LandingHero'
+
+export const JourneyLanding = () => {
+  const { title, intro } = useJourneyContext()
+
+  return (
+    <DefaultLayout>
+      <div>
+        <LandingHero title={title} intro={intro} />
+
+        <div>TODO</div>
+      </div>
+    </DefaultLayout>
+  )
+}

src/landings/components/shared/LandingArticleGridWithFilter.module.scss

@@ -0,0 +1,36 @@
+@import "@primer/css/support/variables/layout.scss";
+@import "@primer/css/support/mixins/layout.scss";
+
+.articleGrid {
+  display: grid;
+  gap: 1.5rem;
+
+  // Mobile: 1 column
+  grid-template-columns: 1fr;
+
+  // Tablet: 2 columns
+  @include breakpoint(md) {
+    grid-template-columns: repeat(2, 1fr);
+  }
+
+  // Desktop: 3 columns
+  @include breakpoint(lg) {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+
+.articleCard {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.cardContent {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.cardFooter {
+  margin-top: auto;
+}