Merge pull request #48 from mrjvs/more-docs

More docs

apps/docs/components/home-card.tsx

@@ -8,8 +8,8 @@ function Card(props: {
   icon: string;
 }) {
   return (
-    <div className="flex flex-col md:flex-row gap-2 border p-6 border-line hover:border-text hover:border-opacity-50 rounded-xl transition-colors duration-100">
-      <Icon icon={props.icon} className="text-2xl text-primary" />
+    <div className="flex flex-col md:flex-row gap-3 border p-6 border-line hover:border-text hover:border-opacity-50 rounded-xl transition-colors duration-100">
+      <Icon icon={props.icon} className="text-2xl -mt-1 text-primary" />
       <div className="flex-1">{props.children}</div>
       <div className="items-center flex md:mt-0 mt-8">{props.right}</div>
     </div>

apps/docs/pages/docs/config/index.tsx

@@ -8,12 +8,12 @@ import {
 
 export default function LandingPage() {
   return (
-    <GuiderLayout meta={{ layout: 'page' }}>
+    <GuiderLayout meta={{ layout: 'page', site: 'config' }}>
       <Hero>
         <Hero.Title>Simple type-safe configuration</Hero.Title>
         <Hero.Subtitle>
-          Configure with json files or environment variables, without losing
-          type-safety
+          Configure your app with JSON files or environment variables without
+          losing type-safety
         </Hero.Subtitle>
         <Hero.Actions>
           <Button to="/docs/config/guide/why-neat-config">Get started</Button>
@@ -23,14 +23,17 @@ export default function LandingPage() {
         </Hero.Actions>
       </Hero>
       <CardGrid>
-        <Card icon="mdi:cube-outline" title="Focus on writing">
-          Effortlessly create beautiful documentation sites with just markdown.
+        <Card icon="material-symbols:lock" title="Schema-first config">
+          Define your config structure using strictly typed and validated
+          schemas.
         </Card>
-        <Card icon="mdi:cube-outline" title="Focus on writing">
-          Effortlessly create beautiful documentation sites with just markdown.
+        <Card icon="material-symbols:cloud" title="Cloud-native">
+          Easily configure applications in the cloud using multiple environment
+          agnostic sources.
         </Card>
-        <Card icon="mdi:cube-outline" title="Focus on writing">
-          Effortlessly create beautiful documentation sites with just markdown.
+        <Card icon="eos-icons:configuration-file" title="Multiple formats">
+          Supports a wide range of configuration sources including JSON files,
+          environment variables and CLI arguments.
         </Card>
       </CardGrid>
     </GuiderLayout>

apps/docs/pages/docs/guider/api-reference/components/guider-content-footer.mdx

@@ -2,8 +2,12 @@
 
 React component that will show the currently configured content footer.
 
-It respects configured `contentFooter` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
+It respects the configured `contentFooter` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
 
+Will show one of:
+ - Nothing if the content footer is set to be hidden.
+ - The default content footer with the configured settings.
+ - The custom component if the content footer has been overriden in the partials.
 
 ## Example
 

apps/docs/pages/docs/guider/api-reference/components/guider-header.mdx

@@ -2,8 +2,12 @@
 
 React component that will show the currently configured navigation partial.
 
-It respects configured `navigation` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
+It respects the configured `navigation` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
 
+Will show one of:
+ - Nothing if the navigation bar is set to be hidden.
+ - The default navigation bar with the configured settings.
+ - The custom component if the navigation bar has been overriden in the partials.
 
 ## Example
 

apps/docs/pages/docs/guider/api-reference/components/guider-layout.mdx

@@ -2,10 +2,14 @@
 
 React component that will show the currently configured layout partial.
 
-It respects configured `layout` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
+It respects the configured `layout` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
 
 The primary use of this component is to make a non-MDX page look like an MDX page. Don't use it if you're already in an MDX File.
 
+Will show one of:
+ - The default layout with the configured settings.
+ - The custom component if the layout has been overriden in the partials.
+
 ## Example
 
 ```tsx
@@ -55,7 +59,7 @@ function GuiderLayout(props);
       </Field.Properties>
     </Field>
     <Field title="children" type="ReactNode">
-      The children of the react component, it will be displayed as the page contents.
+      The children of the React component, it will be displayed as the page contents.
     </Field>
   </Field.Properties>
 </Field>

apps/docs/pages/docs/guider/api-reference/components/guider-logo.mdx

@@ -2,8 +2,12 @@
 
 React component that will show the currently configured logo.
 
-It respects configured `logo` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
+It respects the configured `logo` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
 
+Will show one of:
+ - Nothing if the logo is set to be hidden.
+ - The default logo with the configured settings.
+ - The custom component if the logo has been overriden in the partials.
 
 ## Example
 

apps/docs/pages/docs/guider/api-reference/components/guider-page-end.mdx

@@ -0,0 +1,23 @@
+# `<GuiderPageEnd />`
+
+React component that will show the currently configured page end.
+
+It respects the configured `pageEnd` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
+
+Will show one of:
+ - Nothing if the page end is set to be hidden.
+ - The default page end with the configured settings.
+ - The custom component if the page end has been overriden in the partials.
+
+## Example
+
+```tsx
+<GuiderPageEnd />
+```
+
+
+## Reference
+
+```tsx
+function GuiderPageEnd(): ReactNode;
+```

apps/docs/pages/docs/guider/api-reference/components/guider-page-footer.mdx

@@ -2,8 +2,12 @@
 
 React component that will show the currently configured page footer.
 
-It respects configured `pageFooter` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
+It respects the configured `pageFooter` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
 
+Will show one of:
+ - Nothing if the page footer is set to be hidden.
+ - The default page footer with the configured settings.
+ - The custom component if the page footer has been overriden in the partials.
 
 ## Example
 

apps/docs/pages/docs/guider/api-reference/components/guider-sidebar.mdx

@@ -2,8 +2,12 @@
 
 React component that will show the currently configured sidebar partial.
 
-It respects configured `sidebar` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
+It respects the configured `sidebar` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
 
+Will show one of:
+ - Nothing if the sidebar is set to be hidden.
+ - The default sidebar with the configured settings.
+ - The custom component if the sidebar has been overriden in the partials.
 
 ## Example
 

apps/docs/pages/docs/guider/api-reference/components/guider-toc.mdx

@@ -2,8 +2,12 @@
 
 React component that will show the currently configured table of contents.
 
-It respects configured `toc` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
+It respects the configured `toc` in the layout settings. Read more [about partials](../theme/settings.mdx#about-partials).
 
+Will show one of:
+ - Nothing if the table of contents is set to be hidden.
+ - The default table of contents with the configured settings.
+ - The custom component if the table of contents has been overriden in the partials.
 
 ## Example
 

apps/docs/pages/docs/guider/api-reference/functions/create-not-found-page.mdx

@@ -5,7 +5,7 @@ This function creates a premade 404 page.
 You don't have to use this 404 page, it does nothing special. Feel free to make your own.
 
 <Important>
-  This has be put in `/pages/404.tsx` to work, you can't choose a different location or it won't work.
+  This has be put in `/pages/404.tsx` to work, if you use a different location it won't work.
 </Important>
 
 

apps/docs/pages/docs/guider/api-reference/functions/create-redirect.mdx

@@ -2,6 +2,7 @@
 
 This utility function is an easy way to make redirects work in static site generation mode.
 
+When it's used, it creates a dummy page that redirects when loaded.
 
 ## Example
 

apps/docs/pages/docs/guider/api-reference/functions/use-guider-page.mdx

@@ -50,6 +50,11 @@ function useGuiderPage(): GuiderPageContext;
 
       See [the `useGuider()` page](./use-guider.mdx) for more info.
     </Field>
+    <Field title="navContext" type="object">
+      The navigational context of the page, use it to get the current links in the sidebar.
+
+      See [the `useGuider()` page](./use-guider.mdx) for more info.
+    </Field>
     <Field title="page" type="PageContext">
       Data for the current page content.
 
@@ -59,19 +64,19 @@ function useGuiderPage(): GuiderPageContext;
 
           <Field.Properties>
             <Field title="site" type="string">
-              The site field in the Frontmatter
+              The site field in the Frontmatter.
             </Field>
             <Field title="directory" type="string">
-              The directory field in the Frontmatter
+              The directory field in the Frontmatter.
             </Field>
             <Field title="layout" type="string">
-              The layout field in the Frontmatter
+              The layout field in the Frontmatter.
             </Field>
             <Field title="title" type="string">
-              The title field in the Frontmatter
+              The title field in the Frontmatter.
             </Field>
             <Field title="description" type="string">
-              The description field in the Frontmatter
+              The description field in the Frontmatter.
             </Field>
           </Field.Properties>
         </Field>

apps/docs/pages/docs/guider/api-reference/functions/use-guider.mdx

@@ -76,7 +76,7 @@ function useGuider(metaConf): GuiderContext;
 
           <Field.Properties>
             <Field title="id" type="string" required>
-              The ID of the layout
+              The ID of the layout.
             </Field>
             <Field title="settings" type="PopulatedLayoutSettings">
               The populated layout settings for this layout, read more [about layout settings](../theme/settings.mdx).
@@ -95,7 +95,7 @@ function useGuider(metaConf): GuiderContext;
 
           <Field.Properties>
             <Field title="id" type="string" required>
-              The ID of the directory
+              The ID of the directory.
             </Field>
             <Field title="layout" type="string" required>
               The ID of the layout that needs to be shown for pages in this directory.
@@ -198,5 +198,20 @@ function useGuider(metaConf): GuiderContext;
         </Field>
       </Field.Properties>
     </Field>
+    <Field title="navContext" type="object">
+      The navigational context of the page, use it to get the current links in the sidebar.
+
+      <Field.Properties>
+        <Field title="prev" type="{ group?: string, item: LinkComponent }">
+          The previous page link, according to the order of the sidebar links. It can be null
+        </Field>
+        <Field title="current" type="{ group?: string, item: LinkComponent }">
+          The current page link. It can be null if it isn't present in the sidebar.
+        </Field>
+        <Field title="next" type="{ group?: string, item: LinkComponent }">
+          The next page link, according to the order of the sidebar links. It can be null.
+        </Field>
+      </Field.Properties>
+    </Field>
   </Field.Properties>
 </Field>

apps/docs/pages/docs/guider/api-reference/theme/settings.mdx

@@ -47,6 +47,9 @@ When you overwrite a partial, you can use `useGuiderPage()` to get the current p
 <Field title="pageFooter" type="boolean | () => ReactNode">
   The page footer partial. Check [this section](#about-partials) for information on how to use partials.
 </Field>
+<Field title="pageEnd" type="boolean | () => ReactNode">
+  The page end partial. Check [this section](#about-partials) for information on how to use partials.
+</Field>
 <Field title="logo" type="boolean | () => ReactNode">
   The logo partial. Check [this section](#about-partials) for information on how to use partials.
 </Field>

apps/docs/pages/docs/guider/guides/advanced/customizing-layout.mdx

@@ -11,6 +11,7 @@ Here are all possibilities:
  - `sidebar`: The sidebar navigation menu.
  - `navigation`: The header navigation menu.
  - `contentFooter`: The content footer, placed right below content.
+ - `pageEnd`: The navigation links below the content, but above the content footer.
  - `pageFooter`: The page footer, placed at the very bottom of the page. Disabled by default.
  - `logo`: The logo, shown in the navigation bar and page footer.
  - `pageLayout`: The entire page, cannot be turned off.

apps/docs/pages/docs/guider/guides/advanced/header.mdx

@@ -6,7 +6,7 @@ Learn about configuring the page header.
 
 If you are looking for ways to customise the navigation links in the header, you can [read more here](/docs/guider/guides/config/navigation).
 
-## Github widget
+## GitHub widget
 
 To showcase your GitHub repository with its stars and forks, you can configure a GitHub widget.
 

apps/docs/pages/docs/guider/guides/config/common/api-ref.mdx

@@ -1,5 +1,68 @@
 # API reference + Docs
 
-<Caution>
-This article is a stub, please help by contributing to the docs.
-</Caution>
+A common requirement for expansive documentation sites is having both guides and an API reference.
+
+API reference is a lot more technical and usually isn't very helpful for beginners, but massively helpful if you know the library already and want to fact check something.
+
+The guides is almost the opposite: It's very friendly for beginners, but lacks the completeness of an API reference.
+
+
+## Adding the two sections to your project
+
+The recommended way to add an API reference next to your guides is to use tabs.
+
+Tabs is a configuration option for a Guider site that allows for easy switching between two contexts.
+
+<Steps>
+  <Steps.Step>
+    ### Adding the pages to sub-directories
+
+    First, you have to make sure that your pages are divided in sub-directories. Like so:
+    - `/pages/guides` All your MDX files or pages for your guides
+    - `/pages/api` All your MDX files or pages for your API reference
+  </Steps.Step>
+  <Steps.Step>
+    ### Configuring your tabs
+
+    Your site configuration needs to be split into two `directory()` instances and need to have the configured tabs. Like so:
+
+    ```tsx title="theme.config.tsx" showLineNumbers
+    import { directories, link, defineTheme } from "@neato/guider/theme"
+
+    export default defineTheme({
+      tabs: [
+        link("Guides", "/guides"),
+        link("API reference", "/api"),
+      ]
+      directories: [
+        directory('guides', {
+          sidebar: [
+            // your sidebar items
+          ],
+        }),
+        directory('api', {
+          sidebar: [
+            // your sidebar items
+          ],
+        })
+      ]
+    })
+    ```
+  </Steps.Step>
+  <Steps.Step>
+    ### Creating meta files
+
+    To make your pages tied to your `directory()` instances (and tabs), you'll need to make two meta files for each folder.
+
+    ```json title="/pages/guides/_meta.json"
+    {
+      "directory": "guides"
+    }
+    ```
+    ```json title="/pages/api/_meta.json"
+    {
+      "directory": "api"
+    }
+    ```
+  </Steps.Step>
+</Steps>

apps/docs/pages/docs/guider/guides/deploy/cloudflare.mdx

@@ -11,7 +11,7 @@ Follow the steps below to deploy a Guider project to Cloudflare Pages.
   <Steps.Step>
     ### Make a new Application
 
-    Go to [the cloudflare dashboard](https://dash.cloudflare.com) on under "Workers & Pages" click "Create application".
+    Go to [the Cloudflare dashboard](https://dash.cloudflare.com) on under "Workers & Pages" click "Create application".
   </Steps.Step>
   <Steps.Step>
     ### Select your repository