From 2c672013de6b231eb6eca597dd0cf2c579fd39a9 Mon Sep 17 00:00:00 2001 From: Andy Clifford Date: Mon, 2 Oct 2023 13:33:34 +1300 Subject: [PATCH] Draft pages Created a wrapper function for getCollection which does not return any draft pages when in production. This allows us to incrementally migrate the legacy API reference --- .github/workflows/deploy-dev.yml | 2 +- .github/workflows/publish.yml | 2 +- build.sh | 16 +++++++++-- src/content/api/introduction.mdx | 20 ++++++++++++++ src/content/config.ts | 8 ++++-- src/layouts/BaseLayout.astro | 3 +- src/navigation/sideNavConfig.js | 8 ++++++ src/pages/api/[...slug].astro | 40 +++++++++++++++++++++++++++ src/pages/connections/[...slug].astro | 2 +- src/pages/guides/[...slug].astro | 2 +- src/pages/index.astro | 2 +- src/utils/getCollection.js | 7 +++++ 12 files changed, 100 insertions(+), 12 deletions(-) create mode 100644 src/content/api/introduction.mdx create mode 100644 src/pages/api/[...slug].astro create mode 100644 src/utils/getCollection.js diff --git a/.github/workflows/deploy-dev.yml b/.github/workflows/deploy-dev.yml index 27019eed4..bd65bcce7 100644 --- a/.github/workflows/deploy-dev.yml +++ b/.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: diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 9255a1e91..7785297a3 100644 --- a/.github/workflows/publish.yml +++ b/.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/github-pages-deploy-action@3.7.1 with: GITHUB_TOKEN: ${{ secrets.JEKYLL_PAT }} diff --git a/build.sh b/build.sh index fd11ecd65..ba85ad1cb 100755 --- a/build.sh +++ b/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 diff --git a/src/content/api/introduction.mdx b/src/content/api/introduction.mdx new file mode 100644 index 000000000..d79add689 --- /dev/null +++ b/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. diff --git a/src/content/config.ts b/src/content/config.ts index 902f6ebae..982650c60 100644 --- a/src/content/config.ts +++ b/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 }; diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro index 42b526ccb..f7f350ab8 100644 --- a/src/layouts/BaseLayout.astro +++ b/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 }); --- diff --git a/src/navigation/sideNavConfig.js b/src/navigation/sideNavConfig.js index dc23276bf..142be365d 100644 --- a/src/navigation/sideNavConfig.js +++ b/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' }, + ] + }, ]; diff --git a/src/pages/api/[...slug].astro b/src/pages/api/[...slug].astro new file mode 100644 index 000000000..66b9006e3 --- /dev/null +++ b/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; +--- + +
+
+
+
+

+ { title } +

+
+ + + +
+
+ +
+ diff --git a/src/pages/connections/[...slug].astro b/src/pages/connections/[...slug].astro index 852230464..3ac64012b 100644 --- a/src/pages/connections/[...slug].astro +++ b/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() { diff --git a/src/pages/guides/[...slug].astro b/src/pages/guides/[...slug].astro index 21d6f25db..95d872d1c 100644 --- a/src/pages/guides/[...slug].astro +++ b/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'; diff --git a/src/pages/index.astro b/src/pages/index.astro index e5b69dc7a..3059d7a64 100644 --- a/src/pages/index.astro +++ b/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() { diff --git a/src/utils/getCollection.js b/src/utils/getCollection.js new file mode 100644 index 000000000..80282618f --- /dev/null +++ b/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; + }); +}