DEV Community: docploy

Why you should test your documentation code examples

docploy — Thu, 25 Aug 2022 21:39:00 +0000

Introduction

I worked at a company where we used wiki software to host our internal documentation. The documentation included setup, how-to, onboarding, and architecture pages. Mayhem would ensue after a few years because pages would get out of date. It was hard to tell which Wiki to use when you wanted to find the most up to date information.

One day, I was trying to use a code example that was not running correctly. After an hour of debugging, I found out that the code example was broken. I did not know until I posted on Slack, and someone responded to me. Then, a month later, I saw someone else post the exact same issue. Oops, I was so excited to get past the issue, I ended up not updating the Wiki.

Case for docs-as-code

The primary issue with wikis as developer documentation is they are far removed from the source of truth, the actual code. I will always advocate for having your documentation live with your code if you need to reference any code. This is known as "docs-as-code" because the docs exist within the same version control tool as your code, usually as Markdown files. You can create strong links between your code and your documentation. This allows your documentation to import dependencies from your codebase or show code exactly as it appears in your codebase.

How to import and test code examples

Using Docploy, you can write Markdown files in your docploy/docs folder, add code examples in your docploy/snippets folder, and render those code examples directly in your Markdown files using a snippet tag. Here is an example of how to use a snippet tag:

Here is what the code snippet looks like:

We made the decision to import code from a separate file rather than embed the code directly into a Markdown file because you can use your codebase-specific linters, syntax highlighting, and testing since the file can be treated like an actual file with code since it is an actual file with code.

We will focus on that last item, the testing piece, because it opens the door for us to test that imported code.

Here is the content of the file being imported above:

describe('example', () => {
  it('should return 2', () => {
    // [start]
    function sum() {
      return 1 + 1;
    }
    // [end]
    expect(sum()).toEqual(2);
  });
});

You will notice that we are only rendered a subset of the file. We are actually importing a Jest unit test, and we are only rendering the code between the // [start] and // [end] comment blocks. This is all intentional. This allows you to test your assertions on your code examples before deploying any documentation. This will solve the issue of code examples going out of date. If we import a dependency from the test file whose interface breaks, then the CI build will fail, and we will not be able to deploy the documentation.

Docploy will run the imported file as if it was a regular unit test as part of the CI pipeline. This is why Docploy is tightly integrated into your CI pipeline.

Conclusion

It may seem like overkill to test your documentation code examples, but you will save yourself and your users many hours as your number of documentation pages increase. You will save maintenance time because you do not need to go through the documentation in a regular schedule to manually run all of the code examples. As a user of the documentation, you can be confident that the code examples run, and you are not wasting any time trying to debug broken code examples.

Would you deploy your code to production and just hope everything works out? Would you manually test different product flows every few weeks? It might be fine today, but when there are multiple contributors and many users, you will need an automated way to run tests on your documentation. You should apply modern software engineering principles to your documentation to avoid these issues.

How to build a blog using Next.js and Markdoc

docploy — Mon, 01 Aug 2022 21:35:41 +0000

This post, How to build a blog using Next.js and Markdoc, was originally written on the Docploy blog

We will be using Next.js and Markdoc to create a static blog site from Markdown files. I chose Next.js because the developer experience is amazing for creating static sites. I chose Markdoc as the tool for parsing out our Markdown files.

Install Next.js

Let's start by creating a new Next.js project.

Using yarn

yarn create next-app

Using npm

npx create-next-app

Install Markdoc

Stripe recently released Markdoc as an open source Markdown processor. Stripe uses Markdoc for their documentation, and their documentation is known as one of the best examples of technical documentation. I chose Markdoc because it provides the cleanest writing experience compared to other Markdown processors.

The Markdown is decoupled from any implementation details, so when you are editing your Markdown files, you can fully focus on writing content.

Markdoc also supports validating your Markdown files, which will make it easy to enforce any structural, syntactical, or grammatical rules if your blog has many contributors.

Let's install the Markdoc package.

Using yarn

yarn add @markdoc/markdoc --save

Using npm

npm install @markdoc/markdoc --save

Create your first blog post

Create a new folder in your project called posts/. This is where your Markdown blog post files will live.

Create a new Markdown file posts/welcome-to-my-new-blog.md and add the following sample content:

---
title: "Welcome to my new blog"
date: 2022-07-27
---

Welcome to my new blog created using Next.js and Markdoc.

Set up your first route

Let's begin by setting up a new route for your blog posts.

Create an empty file in your project under the path pages/blog/[slug].js.

Next.js automatically sets up routes for you when you create files under the pages directory.

The [slug].js in pages/blog/[slug].js means a user can go to /blog/welcome-to-my-new-blog, and the [slug].js file will be responsible for handling the route and returning the contents of the matching Markdown file.

Using the getStaticPaths function

We will create a getStaticPaths function in [slug].js that will return possible blog post URLs based on our Markdown files in the posts/ directory. Next.js looks for the getStaticPaths function as part of the framework to make the work easier for you.

First, install the glob-promise package so we can find all of our Markdown files in the posts/ folder in one line of code.

Using yarn

yarn add glob-promise --save

Using npm

npm install glob-promise --save

Add the getStaticPaths function

Create a getStaticPaths function (annotated below) in [slug].js that looks like the following:

import glob from 'glob-promise';
import path from 'path';

export const getStaticPaths = async () => {
  // Our Markdown files are stored in the posts/ directory
  const POSTS_DIR = path.join(process.cwd(), 'posts');

  // Find all Markdown files in the posts/ directory
  // With The glob-promise library, we can use a one liner to find our Markdown files
  const postPaths = await glob(path.join(POSTS_DIR, '**/*.md'));

  // For each filename, the slug is the filename without the .md extension
  const paths = postPaths.map((postPath) => {
    const slug = path.basename(postPath, path.extname(postPath));
    return { params: { slug } };
  });

  // Return the possible paths
  return { paths, fallback: false };
};

Next, we need to read the Markdown file when the user visits a blog post route.

Read your Markdown files with Markdoc

Similar to how Next.js automatically supports getStaticPaths function, Next.js also supports an exported getStaticProps. We will use the getStaticProps function to pass the blog post data to the React component, so we can show the user the blog post. We add the getStaticProps function in the same [slug].js file that we have been working on.

// ... imports from the last step here ...
import Markdoc from '@markdoc/markdoc';
import fs from 'fs';

// This config tells Markdoc to look for our Paragraph React component (to be created in another step)
const config = {
  nodes: {
    paragraph: {
      render: 'Paragraph',
    },
  },
};

export const getStaticProps = async (context) => {
  // Our Markdown files are stored in the posts/ directory
  const POSTS_DIR = path.join(process.cwd(), 'posts');

  // Generate the local Markdown path from the URL slug
  const {
    params: { slug },
  } = context;
  const fullPath = path.join(POSTS_DIR, slug + '.md');

  // Read the Markdown file contents
  const source = fs.readFileSync(fullPath, 'utf-8');

  // Use Markdoc to create a tree of tokens based on the Markdown file
  const ast = Markdoc.parse(source);

  // Create a renderable tree
  const content = JSON.stringify(Markdoc.transform(ast));

  // Return the content as a prop to the React component for now
  // We will render the content in the next section
  return {
    props: {
      content,
    },
  };
};

Render your Markdown in a React component

We will add our last piece of code in the same [slug].js file which will return a React component. As part of Next.js, we can export default a React component, and Next.js will render that React component for us. Our React component uses Markdoc.renderers.react(...) to convert the renderable tree into a React element.

// ... other imports here ...
import React from 'react';

// Return our custom Paragraph component that adds custom Tailwind classes
const components = {
  Paragraph: ({ children }) => {
    return <p className="leading-relaxed mb-8 text-lg">{children}</p>;
  },
};

// Create a React component using Markdoc's React renderer and our list of custom components.
const BlogPostPage = (props) => {
  const { content } = props;
  const parsedContent = JSON.parse(content);

  return (
    <div>
      {Markdoc.renderers.react(parsedContent, React, {
        components,
      })}
    </div>
  );
};

export default BlogPostPage;

Render a list of your posts

Finally, we need to render a list of your posts when your users go to /blog.

Create a new file, pages/blog.js. Remember, Next.js will automatically set up the routing for /blog since the new file was created under the pages/ directory. Once again, Next.js will render the default exported React component that gets returned from pages/blog.js.

Install gray-matter

Install the gray-matter package so we can extract the title from the Markdown metadata.

Using yarn

yarn add gray-matter --save

Using npm

npm install gray-matter --save

Install dates-fns

Install the date-fns package to make it easier to format dates.

Using yarn

yarn add date-fns --save

Using npm

npm install date-fns --save

Here is the final pages/blog.js file with an explanation of the lines.

// ... add imports if they haven't been added yet ...
import Link from 'next/link';
import { format } from 'date-fns';
import fs from 'fs';
import glob from 'glob-promise';
import matter from 'gray-matter';
import path from 'path';

export const getStaticProps = async () => {
  // Find all Markdown files in the /posts directory
  const POSTS_DIR = path.join(process.cwd(), 'posts');
  const postPaths = await glob(path.join(POSTS_DIR, '**/*.md'));
  const posts = postPaths.map((postPath) => {
    const slug = path.basename(postPath, path.extname(postPath));
    const source = fs.readFileSync(postPath, 'utf-8');

    // Use gray-matter to fetch the data between the `---` at the top of our Markdown files.
    const matterResult = matter(source);
    const { title, date } = matterResult.data;

    return {
      title,
      date,
      slug,
    };
  });

  // Sort the posts by date
  const sortedPosts = posts.sort((a, b) => b.date - a.date);

  // We need to format the dates into strings because Next.js expects the props to be serializable as JSON.
  const parsedDatePosts = sortedPosts.map((post) => {
    return {
      ...post,
      date: format(post.date, 'MM/dd/yyyy'),
    };
  });
  return { props: { posts: parsedDatePosts } };
};

const Blog = (props) => {
  const { posts } = props;
  return (
    <div>
      {posts.map((post, i) => {
        return (
          <div key={i}>
            <Link href={'/blog/' + post.slug}>
              <a>
                <h1>{post.title}</h1>
              </a>
            </Link>
          </div>
        );
      })}
    </div>
  );
};

export default Blog;

Conclusion

You can start up your project locally by running yarn dev.

Visit https://localhost:3000/blog, and you'll see a list of blog posts. In this case, we only have one blog post. If you click on the name of the blog post, you will go to the full blog post.

You have achieved the ultimate victory. You now have a blog created using Next.js and Markdoc.

I have created a repo that you can clone use as a playground: Next.js and Markdoc example.

If you have any questions, send a message to me at @docploy on Twitter.