feat: Intro (#334)

Author: abernier

docs/getting-started/authoring.mdx

@@ -5,6 +5,10 @@ sourcecode: docs/getting-started/authoring.mdx
 nav: 1
 ---
 
+<Intro>
+  This is a guide on how to write documentation. We support all [GitHub Flavored Markdown](https://github.github.com/gfm/) syntax, plus some custom components that are described here.
+</Intro>
+
 In your `MDX` folder, create any `path/to/my-document.mdx`:
 
 ```md
@@ -37,6 +41,26 @@ You can use any [GitHub Flavored Markdown](https://github.github.com/gfm/) synta
 
 Plus, all exported [`components/mdx/index.tsx`](components/mdx/index.tsx) MDX components.
 
+### Intro
+
+```md
+<Intro>
+  This is an intro. Here you can write a short description of the article, longer than the `description`, eventually with [links](#void), lists, etc.
+  
+  Multiple paragraphs are also possible, or anything.
+</Intro>
+```
+
+<details>
+  <summary>Result</summary>
+
+<Intro>
+  This is an intro. Here you can write a short description of the article, longer than the `description`, eventually with [links](#void), lists, etc.
+  
+  Multiple paragraphs are also possible, or anything.
+</Intro>
+</details>
+
 ### `Img`
 
 Relative images are supported. Eg, inside your [`MDX`](introduction#configuration:~:text=MDX) folder:

docs/getting-started/github-actions.mdx

@@ -4,7 +4,11 @@ description: Call from your CI
 nav: 3
 ---
 
-`pmndrs/docs` provides a [`build.yml`](.github/workflows/build.yml) reusable workflow, any project can use:
+<Intro>
+  This project provides a [`build.yml` reusable workflow](https://docs.github.com/en/actions/sharing-automations/reusing-workflows#calling-a-reusable-workflow) you can easily call from your own project workflow.
+</Intro>
+
+In your `.github/workflows` folder, create a eg. `docs.yml` file:
 
 ```yml
 uses: pmndrs/docs/.github/workflows/build.yml@v2

docs/getting-started/introduction.mdx

@@ -4,6 +4,10 @@ description: Documentation generator for `pmndrs/*` projects.
 nav: 0
 ---
 
+<Intro>
+  A static MDX documentation generator, with a GitHub [reusable workflow](./github-actions.mdx). It is primarily used for some `pmndrs/*` projects, but will work for anyone.
+</Intro>
+
 ![Gutenberg lithography](gutenberg.jpg)
 
 [Those projects](https://github.com/search?q=%22uses%3A+pmndrs%2Fdocs%2F.github%2Fworkflows%2Fbuild.yml%22+language%3AYAML&type=code&l=YAML) are known to be using this generator.

src/app/[...slug]/page.tsx

@@ -37,7 +37,7 @@ export default async function Page({ params }: Props) {
 
   return (
     <>
-      <div className={cn('my-8 border-b', 'border-outline-variant/50')}>
+      <div className={cn('mb-6 mt-8 border-b', 'border-outline-variant/50')}>
         <h1 className="mb-2 text-5xl font-bold tracking-tighter">{doc.title}</h1>
         {!!doc?.description?.length && (
           <p className={cn('my-2 text-base leading-5', 'text-on-surface-variant/50')}>

src/components/mdx/Intro/Intro.tsx

@@ -0,0 +1,6 @@
+import cn from '@/lib/cn'
+import { ComponentProps } from 'react'
+
+export function Intro({ className, ...props }: ComponentProps<'div'>) {
+  return <div {...props} className={cn(className, 'my-6 text-xl leading-relaxed')} />
+}

src/components/mdx/Intro/index.ts

@@ -0,0 +1 @@
+export * from './Intro'

src/components/mdx/index.tsx

@@ -5,6 +5,7 @@ export * from './Gha'
 export * from './Grid'
 export * from './Hint'
 export * from './Img'
+export * from './Intro'
 export * from './Summary'
 export * from './Toc'
 
@@ -54,7 +55,7 @@ export const ol = ({ className, ...props }: ComponentProps<'ol'>) => (
 )
 export const li = (props: ComponentProps<'li'>) => <li className="my-1" {...props} />
 
-export const p = (props: ComponentProps<'p'>) => <p className="my-4 text-base" {...props} />
+export const p = (props: ComponentProps<'p'>) => <p className="my-4" {...props} />
 
 export const hr = (props: ComponentProps<'hr'>) => (
   <hr className="my-4 mb-8 border-outline-variant/50" {...props} />