Finch Docs v2 is built using Tailwind CSS and Next.js and powered by Markdoc, the new open source Markdown-based authoring framework (which Stripe uses to power their own documentation website).
Live demo -> https://finch-docs-v2.vercel.app/
To get started with this template, first install the npm dependencies:
npm install
cp .env.example .env.localNext, run the development server:
npm run devFinally, open http://localhost:3000 in your browser to view the developer documentation.
When writing documentation, let’s avoid using the term “user” when referring to different types of people. This also applies to our documentation.
Finch’s customer → “Developer”
A Developer’s customer → “Customer” (or sometimes “Employer”)
A Developer’s customer’s customer → “Employer”
Finch’s frontend component that connects an employer’s provider with a developer → “Finch Connect”
An employer’s HRIS, Payroll, or Application Tracking systems → “Provider”
Avoid using acronyms in documentation. The time they "save" does not justify the exclusion someone feels when they don't understand an acronym.
Avoid using sentences that use "refer to here" in documentation.
- Bad: "Your customer needs to go through Finch Connect again to reconnect their employment system if their initial connection has gone stale. You can read more here."
- Good: "Your customer needs to go through Finch Connect again to reconnect their provider if their initial connection has gone stale."
You can start editing documents by modifying the files in the /src/docs folder. The site will auto-update locally as you edit these files.
- Create a new .md file in the
src/pages/docsfolder - Update the navigation object in
src/components/Layout.jsxwith a link.
Markdoc is a Markdown-based document format and a framework for content publishing. Markdoc adds a few extensions to the markdown syntax to enable a powerful way to extend the documentation with custom components. Tags are the main way of adding custom componets to a Markdoc document.
Markdoc comes with a few built-in tags, but Finch has created a few custom-defined tags. You can view them back going to /markdoc/tags.js. Once a tag has been defined (even using a custom React component), you can embed the tag in a regular markdown file by enclosing the tag with {% and %}.
Our custom tags are listed below:
{% figure src="/images/image.png" alt="description of image" / %}{% callout type="warning" title="Note" %}
text
{% /callout %}{% tabs %}
{% tab label="Request" %}
{% /tab %}
{% tab label="Response" %}
{% /tab %}
{% /tabs %}Since this website uses the @tailwindcss/typography plugin for styling markdown articles, if a custom tag (like src/components/Provider-Compatibility.jsx) is embedded into an article, but has custom styling, add the not-prose css style to undue typography styles.
We should probably start validating Markdoc tag syntax.
Our developer docs uses Stoplight.io/elements package to display our OpenAPI API Reference documentation. The URL to this OpenAPI specification is located in https://github.com/Finch-API/finch-docs/tree/main/reference/employer. This link needs to be updated in src/pages/api-reference.jsx and src/components/layout.jsx if this ever changes.
To learn more about the technologies used in this site template, see the following resources:
- Tailwind CSS - the official Tailwind CSS documentation
- Next.js - the official Next.js documentation
- Headless UI - the official Headless UI documentation
- Markdoc - the official Markdoc documentation
- DocSearch - the official DocSearch documentation