Merge pull request #782 from centrapay/draft-page

Draft page

.github/workflows/deploy-dev.yml

@@ -26,7 +26,7 @@ jobs:
         with:
           node-version: 18
       - run: yarn install --frozen-lock-file
-      - run: ./build.sh http://centrapay-docs.dev.s3-website-ap-southeast-1.amazonaws.com
+      - run: ./build.sh
       - name: Configure AWS Credentials
         uses: aws-actions/configure-aws-credentials@v2
         with:

.github/workflows/publish.yml

@@ -27,7 +27,7 @@ jobs:
       - run: yarn install --frozen-lock-file
       - run: yarn lint
       - run: yarn test
-      - run: ./build.sh
+      - run: ./build.sh --prod
       - uses: JamesIves/[email protected]
         with:
           GITHUB_TOKEN: ${{ secrets.JEKYLL_PAT }}

build.sh

@@ -2,7 +2,17 @@
 
 set -euo pipefail
 
-url="${1:-}"
+mode="development"
+
+while [ $# -gt 0 ]; do
+  case $1 in
+    --prod)
+      shift
+      mode="production"
+    ;;
+  esac
+  shift
+done
 
 cd legacy
 
@@ -11,8 +21,8 @@ bundle exec jekyll build
 
 cd ../
 
-if [[ -n "$url" ]]; then
-  yarn build --site "$url"
+if [ "$mode" == "development" ]; then
+  yarn build --mode "$mode" --site "http://centrapay-docs.dev.s3-website-ap-southeast-1.amazonaws.com"
 else
   yarn build
 fi

src/content/api/introduction.mdx

@@ -0,0 +1,20 @@
+---
+title: API Introduction
+description: Introduction to the API Reference
+nav:
+  path: API/Getting Started
+  order: 1
+---
+
+The Centrapay API is an [RMM](https://en.wikipedia.org/wiki/Richardson_Maturity_Model)
+level 2 RESTful web service which expresses operations in terms of HTTP verbs on
+resource-oriented URLs. API endpoint definitions in these docs are grouped by resource
+type along with definitions for the associated resource types.
+
+Most API calls require [authentication](https://docs.centrapay.com/api/auth) using an API key or
+JWT. HTTP requests and responses usually have JSON payloads and use
+"application/json" as the content type.
+
+Some API features may be flagged as **EXPERIMENTAL**. These API features may be
+removed or changed without warning and should not be relied on in a production
+setting.

src/content/config.ts

@@ -1,10 +1,11 @@
 import { z, defineCollection } from 'astro:content';
 
-const guidesCollection = defineCollection({
+const collection = defineCollection({
   schema: z.object({
     title: z.string(),
     description: z.string(),
     img: z.string().optional(),
+    draft: z.boolean().optional().default(false),
     nav: z.object({
       title: z.string().optional(),
       path: z.string(),
@@ -14,6 +15,7 @@ const guidesCollection = defineCollection({
 });
 
 export const collections = {
-  'guides': guidesCollection,
-  'connections': guidesCollection,
+  'guides': collection,
+  'connections': collection,
+  'api': collection
 };

src/layouts/BaseLayout.astro

@@ -4,7 +4,7 @@ import MessagesBubbleDouble from '../components/icons/MessagesBubbleDouble.vue';
 import Footer from '../components/Footer.vue';
 import '../assets/css/tailwind.css';
 import '@fontsource/inter';
-import { getCollection } from 'astro:content';
+import { getCollection } from '../utils/getCollection';
 import Navigation from '../navigation/Navigation';
 import sideNavConfig from '../navigation/sideNavConfig'
 
@@ -26,6 +26,7 @@ const metaTitle = title ? title + ' - Centrapay Docs' : 'Centrapay Docs';
 const content = await Promise.all([
   ...await getCollection('guides'),
   ...await getCollection('connections'),
+  ...await getCollection('api')
 ])
 const navigation = Navigation.create({ nav: sideNavConfig, content });
 ---

src/navigation/sideNavConfig.js

@@ -18,4 +18,12 @@ export default [
       { title: 'Farmlands' },
     ]
   },
+  import.meta.env.MODE === 'development' && {
+    title: 'API',
+    subTitle: 'For developers',
+    icon: 'Settings',
+    children: [
+      { title: 'Getting Started' },
+    ]
+  },
 ];

src/pages/api/[...slug].astro

@@ -0,0 +1,40 @@
+---
+import { getCollection } from '../../utils/getCollection';
+import Prose from '../../components/Prose.vue';
+import TocNav from '../../components/TocNav.vue';
+import BaseLayout from '../../layouts/BaseLayout.astro';
+import customComponents from '../../utils/customComponents';
+
+export async function getStaticPaths() {
+  const api = await getCollection('api');
+  return api.map(entry => ({
+    params: { slug: entry.slug },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content, headings } = await entry.render();
+const { title, description } = entry.data;
+---
+<BaseLayout title={title} description={description}>
+  <div class="relative mx-auto desktop-gutters flex justify-center">
+    <div class="min-w-0 max-w-2xl flex-auto px-8 pb-16 pt-8 xl:pt-16 lg:max-w-none">
+      <article>
+        <header class="mb-9 space-y-1" >
+          <h1
+            class="font-display text-3xl tracking-tight text-slate-900"
+          >
+            { title }
+          </h1>
+        </header>
+        <Prose client:load>
+          <Content components={customComponents}/>
+        </Prose>
+      </article>
+    </div>
+    <div class="hidden xl:sticky border-none xl:top-[4.5rem] xl:block xl:h-[calc(100vh-4.5rem)] xl:flex-none xl:py-16 xl:pr-6 overflow-y-auto">
+      <TocNav client:load headings={headings} />
+    </div>
+  </div>
+</BaseLayout>

src/pages/connections/[...slug].astro

@@ -1,5 +1,5 @@
 ---
-import { getCollection } from 'astro:content';
+import { getCollection } from '../../utils/getCollection';
 import customComponents from '../../utils/customComponents';
 
 export async function getStaticPaths() {

src/pages/guides/[...slug].astro

@@ -1,5 +1,5 @@
 ---
-import { getCollection } from 'astro:content';
+import { getCollection } from '../../utils/getCollection';
 import Prose from '../../components/Prose.vue';
 import TocNav from '../../components/TocNav.vue';
 import BaseLayout from '../../layouts/BaseLayout.astro';

src/pages/index.astro

@@ -2,7 +2,7 @@
 import BaseLayout from '../layouts/BaseLayout.astro';
 import FeaturedGuideCard from '../components/FeaturedGuideCard.astro';
 import FeaturedContentCard from '../components/FeaturedContentCard.astro';
-import { getCollection } from 'astro:content';
+import { getCollection } from '../utils/getCollection';
 import Prose from '../components/Prose.vue';
 
 export async function getStaticPaths() {

src/utils/getCollection.js

@@ -0,0 +1,7 @@
+import { getCollection as get } from 'astro:content';
+
+export async function getCollection(collection) {
+  return await get(collection, ({ data }) => {
+    return import.meta.env.MODE !== 'production' || !data.draft;
+  });
+}