Most docs sites are not set up for this. Some block AI crawlers by default in robots.txt and don’t know it. Others rely on JavaScript rendering that crawlers can’t see. Others have great content that buries the answer under three paragraphs of context.

Here’s what we’ve been testing and fixing across consulting projects.

Four tests to run now

Test 1: is your site crawlable without JavaScript?

Open your docs in a fresh browser. Disable JavaScript. Reload.

If the page loads and the content is readable, AI crawlers can probably read it too. If not, you have a problem. Most crawlers don’t execute JavaScript. They see what curl sees.

You can also test directly:

curl -A "ClaudeBot" https://your-docs.com/getting-started

If the response is a mostly empty HTML shell with a <script> tag, AI crawlers are getting the same empty shell.

Test 2: is your robots.txt blocking AI crawlers?

Check https://your-docs.com/robots.txt for these user agents:

GPTBot        # OpenAI
ClaudeBot     # Anthropic
PerplexityBot # Perplexity
CCBot         # Common Crawl (used by many LLMs)
Google-Extended # Google's AI training bot

If any of these are disallowed, AI crawlers are skipping your site. Some CDNs and hosting platforms block AI bots by default as part of “bot protection” settings. Worth checking.

Test 3: do you rank for questions users actually ask?

Pick three questions a developer might ask about your product. Google them with your company name.

Example: "biel.ai create account", "biel.ai docusaurus install", "biel.ai customize widget"

If you don’t rank in the first results, AI probably can’t find you either. AI retrieval uses the same signals as search engines, weighted differently. This applies both to live retrieval (what ChatGPT and Claude Code query in real time) and to training data (what the models learned from). No Google ranking usually means no AI ranking in either case.

Test 4: does your docs answer common questions up front?

Pick three common questions users ask about your product. Open the relevant docs page for each.

Is the answer on the page? Is it in the first paragraph, or buried three paragraphs deep?

AI agents retrieve a chunk of content and return an answer based on it. If your page opens with context before the answer, the agent will summarize the context instead. If the answer is missing entirely, the agent will either hallucinate or say it doesn’t know.

The 90%: indexable + useful + popular

Those four tests measure three things:

• Indexable: can AI crawlers access your content?

• Useful: does your content answer what users ask?

• Popular: is your content referenced by high-signal sources?

Cover these three and you’ve done 90% of the work.

The 10%: extra credit

We can’t know exactly which retrieval methods each AI system uses. The more signals we provide, the more discoverable our content becomes. If you’ve covered the basics and want to push further, here’s what to add.

Publish an llms.txt file. Like sitemap.xml but for LLMs. A plain text file at your site root describing what your documentation contains and how it’s organized.

# Biel.ai Docs
> AI chatbot for technical documentation

## Getting Started
- [Install in Docusaurus](https://docs.biel.ai/docusaurus)
- [Install in MkDocs](https://docs.biel.ai/mkdocs)

## API Reference
- [Authentication](https://docs.biel.ai/api/auth)

Still emerging, still evolving, but increasingly supported.

Serve markdown URLs. Crawlers and agents work best with clean markdown over bloated HTML. You can serve the same page at .md for a cleaner, token-efficient version. Example: yoursite.com/api.md instead of making them parse your HTML, CSS, navigation, and cookie banner.

Structured data and metadata. Add Schema.org markup for pricing, FAQs, and product info. Keep Open Graph tags and meta descriptions accurate. Use page metadata to describe what each page is about, including keywords and synonyms for concepts users might call by different names (e.g. “asset” vs “token”).

Publish machine-readable schemas. Make your OpenAPI specs publicly available. Same for GraphQL schemas, Protocol Buffers, or any structured contract your API exposes. Agents can parse these directly, no HTML scraping needed.

Measure where you stand

Fern’s Agent Score evaluates your docs against 22 checks covering most of the above. You get a grade and a list of issues, and a prompt you can paste into Claude Code to fix them automatically.

We ran it on our own docs and got a C on the first run. As they say, “the shoemaker’s son always goes barefoot”.

But this didn’t stop Biel.ai from ranking first when asking ChatGPT for the best AI chatbot for Docusaurus. Because we focused on the basics first.

Start with the basics

The 90% is where most of the value is. Be crawlable, improve the quality of your docs, make them popular. The extra 10% is worth doing if you’re already in good shape, but don’t skip the basics to chase it.

Most docs teams are still catching up. Start with the basics now and your docs will be easier to find when everyone else is still figuring it out.

Across the industry, when companies need to reduce headcount, documentation teams are among the first on the list. Sometimes to cut costs, sometimes to justify AI investment. But the stated logic tends to be the same: AI can write docs now, so why pay people to do it?

Not every company is moving in this direction. And the ones that aren’t have a very different theory about what documentation is for.

The companies cutting writers

There are AI agents that detect code changes and draft doc updates. Tools that generate release notes, changelog entries, and API references from code and product specs. They’re fast, and for companies shipping quickly, that speed is a real advantage. On paper, you no longer need a dedicated team for this.

The question isn’t whether AI can produce docs. It’s whether it can maintain them, structure them, and make them useful over time without someone thinking about that full-time.

In practice, documentation gets reassigned to engineers or product managers, who use AI to draft it. In theory, it works. In reality, developers have already absorbed testing, infrastructure as code, CI/CD, on-call. Now add docs strategist to the pile. They have more on their plate, not less. Docs get written when there’s time, which is rarely.

Nobody reviews whether the content actually helps a user get from A to B. Nobody maintains the getting started guide when the SDK changes. Nobody decides what shouldn’t be documented.

And to be fair, there’s a real argument that the people who build the thing should document the thing. I don’t disagree. We’ve been advocating for that even before AI entered the picture. But there’s a difference between engineers contributing to docs and engineers being fully responsible for docs strategy, maintenance, and information architecture on top of everything else they already own. I’m describing a pattern I’ve seen, not citing a controlled study, but from the contracts we’ve picked up after layoffs like these, it’s consistent: the docs drift, support tickets go up, onboarding takes longer, and there’s nobody whose job it is to fix it.

Could this work with strong processes, dedicated doc sprints, or better guardrails around AI-generated content? Maybe. I haven’t seen it succeed at scale yet, but I’d welcome examples that prove otherwise.

The companies investing in writers

On the other side, some companies are hiring more writers, not fewer, and using AI to augment them. Their reasoning: documentation is now the source material that every AI system depends on. AI coding assistants, chatbots, support agents. They all consume your docs. If the docs are wrong, the AI is wrong.

Here’s a concrete example. An AI coding assistant trained on outdated API docs will confidently suggest deprecated endpoints and wrong parameter names. Developers follow the suggestion, hit errors, file issues, and lose trust in the tool. The root cause isn’t the AI. It’s the docs the AI was reading.

These companies treat documentation as infrastructure. The foundation for how users and AI understand their product. The better the docs, the better every experience built on top of them.

Anyone who’s actually used AI to write or code knows it’s a back and forth. You prompt, you review, you correct, you re-prompt. The output needs judgment. Someone who knows what good docs look like, not just someone who can generate more of them.

But it’s not just about producing docs. There’s also a role AI can’t fill, at least for now. Technical writing has never been 100% writing. It’s deciding what gets documented and what doesn’t. Knowing who to ask for the right information. Evaluating whether docs are useful or need rework. Figuring out what order things should be learned in. And knowing when adding more pages actually makes things harder to find. An AI will happily generate pages for everything. A good docs team knows when to say no.

Where I stand

I run a documentation engineering consultancy. I have skin in the game, and I’ll be honest about that. We’ve had contracts cancelled because companies decided AI could handle the docs. We’ve also gained contracts from companies that understand docs are the fuel for AI.

Our position: AI makes writers more capable, not redundant. Writers who use AI to draft, then edit, verify, test, and structure produce better output than before. Maybe the companies that cut their teams had other reasons for making that call. But creating better docs wasn’t one of them.

The companies investing in documentation right now understand something simpler: every answer AI generates is only as good as the docs it’s reading.

The assistant kept responding “I couldn’t find information about this” for basic things. Export data. Reset password. Delete account.

Support had been answering these verbally for years. Everyone assumed it was documented, but it wasn’t.

Why basic flows go undocumented

When a team ships something new, they want to document the shiny parts. The feature they spent months building. The complex integration that’s hard to understand without a guide.

Nobody writes a page about how to reset a password. It feels too obvious.

Then support starts getting questions. They answer them in 30 seconds over chat, and writing a whole doc page for that feels like overkill. So it stays verbal. Months pass, new support agents join, and they learn the answers from colleagues, not from docs. At some point everyone just assumes it’s written down somewhere.

An AI assistant breaks this cycle. It can only answer what’s documented. It doesn’t know what support told a user last week, and it doesn’t have access to Slack threads or old tickets. In our case, that’s intentional. We only train it on curated, reviewed documentation.

So when a user asks “How do I export my data?” and the assistant says “I couldn’t find information about this,” that gap is no longer invisible. It shows up in the logs, every day. You can’t ignore it.

Use the gaps

Once we documented the missing flows, tickets dropped. The assistant started answering questions it couldn’t before.

But here’s the part we didn’t expect: the “I don’t know” responses told us exactly what to write next. We just looked at what users asked most and started there.

AI assistants don’t fix documentation problems. They make them visible.

Two years ago, they’d open your docs site and read the guide. Today, they type “How do I authenticate with this API?” in Claude Code. The AI answers, writes the code, and moves on. Your docs site never sees a pageview.

Top engineers at Anthropic and OpenAI report that AI now writes 100% of their code. If developers aren’t even writing code themselves, they’re definitely not browsing your docs to figure out how to write it.

We're seeing this in the documentation projects we work on. AI-driven traffic to docs sites is growing while human visits drop. Mintlify reports that almost half of documentation site traffic now comes from AI agents, not humans. Your docs have a new primary reader. It doesn’t browse. It queries.

From reading to asking

Documentation always competed with Stack Overflow, GitHub issues, and asking a coworker on Slack. AI coding assistants just won that competition.

When you can describe your problem in natural language and get working code back, in context, inside your editor, there's no reason to open a docs site.

But that doesn’t mean docs matter less. If anything, accuracy matters more now. A human reading a confusing paragraph will slow down, re-read, maybe search for other sources. An AI will just pick an interpretation and ship it.

The problem with public AI models

When a developer asks an AI about your product, the model either relies on training data or searches the web. Both are broken.

Training data is stale. If you shipped a new SDK version last month, the model doesn’t know. It’ll suggest deprecated methods with full confidence. Web search relies on SEO. The model might find a three-year-old Medium article instead of your current API reference. Your content’s discoverability depends on how well you rank, not on how good your docs are.

Neither approach has a special relationship with your documentation. It doesn’t know your custom error codes or the migration guide you published last Tuesday.

The result: AI generates code based on outdated examples and wrong parameter names. The developer doesn’t even know the answer was wrong until something breaks.

It gets worse for internal docs

If public docs have a discoverability problem, internal docs are completely invisible.

Your internal wiki, your Confluence spaces, your private Notion pages. AI models can’t see any of it. A new engineer joins your team, asks their AI assistant “How do I deploy to staging?”, and gets nothing useful. The model wasn’t trained on your deployment runbook. It can’t search your internal network.

Your internal documentation is invisible to every AI tool your developers use daily. That’s a real problem.

Connect your docs to the tools developers actually use

There’s a fix for this. Instead of hoping AI models happen to find your docs, you can connect your documentation directly to the AI tools developers are already using.

This is what the Model Context Protocol (MCP) enables. It’s an open standard that lets AI assistants connect to external data sources. Think of it as a bridge between an AI coding assistant and your documentation.

With an MCP server pointing at your docs, the assistant fetches answers directly from your content. Not from training data. Not from Google. From your docs, in real time.

And here’s the part most people miss: you register a description of what your docs contain. The AI uses that description to decide when to query your docs. If a developer is working with your SDK and hits an authentication problem, the assistant knows your docs are the right place to look. It’s not a keyword search. The AI decides based on context.

What this means for documentation teams

Your docs go from a website people browse to a data source AI tools query. That changes things.

Content quality matters more, not less. Every ambiguity, every outdated example, every missing step gets amplified. Bad docs produce bad AI answers at scale. Good docs produce answers that make developers trust your product.

Internal docs become reachable. That deployment runbook, your team’s coding standards, your architecture decision records. MCP can expose them to AI assistants inside your organization.

You also get better feedback. When AI assistants query your docs, you can see what questions are being asked. That’s direct signal about what developers are trying to do. Better than pageview analytics ever was.

What this doesn’t fix

MCP doesn’t fix bad docs. If your content is incomplete or outdated, AI will serve incomplete, outdated answers. Just faster.

And it doesn’t eliminate hallucinations. But it gets things wrong less when it has access to the right content. Your docs site is still the canonical source of truth. When AI gives a wrong answer, that’s where developers go to verify. MCP just makes your content reachable from more places.

Where to start

Start thinking about how AI assistants consume your content. Not how humans read it. How machines query it.

Structured content, clear headings, explicit examples. These matter even more now. Your new reader doesn’t browse pages. It parses them.

Look into how MCP can work for your docs. Connect it to the tools your team already uses. See what questions come in.

Your docs are already being consumed by AI. The question is whether you’re serving the right answers or letting the model guess.

2025 was full of growth and learning.

At TechDocs Studio, we helped clients build scalable documentation infrastructure, automate workflows, and improve their docs, seeing firsthand how targeted improvements transform daily work for teams.

We also reinvested in our own products, including Biel.ai and PushFeedback, tackling common documentation challenges our customers face. Watching these tools start to make a real difference has been incredibly rewarding.

This year reinforced that growth is not just about new contracts, but about trust, collaboration, and celebrating small wins together.

I’m grateful to everyone who made this year possible:

• 𝗖𝗼𝗿𝗲 𝘁𝗲𝗮𝗺: Àlex, Raúl. Thank you for bringing skill, dedication, joy to every project.

• 𝗡𝗲𝘄 𝗰𝗹𝗶𝗲𝗻𝘁𝘀: Kristy-Leigh, Matthew, Rustom, Alex, Jimmy. Thank you for trusting us.

• 𝗟𝗼𝗻𝗴-𝘁𝗲𝗿𝗺 𝘀𝘂𝗽𝗽𝗼𝗿𝘁𝗲𝗿𝘀: Anna, Tzach, Elena, Jorge, Alberto, Rich, Nate. Thank you for your continued trust and support over the years.

• 𝗘𝗻𝗮𝗯𝗹𝗲𝗿𝘀: Pablo, Juan Luis. Thank you for connecting us with exceptional people.

• 𝗙𝗲𝗲𝗱𝗯𝗮𝗰𝗸 𝗰𝗵𝗮𝗺𝗽𝗶𝗼𝗻𝘀: Lars, Tim, Harshil, Seonaid, Elena K. Your feedback improved our tools for everyone.

• 𝗜𝗻𝘀𝗽𝗶𝗿𝗮𝘁𝗶𝗼𝗻: Ivan, Sabela, Cristina, Aleix, Xavi. I’ve learned a ton from all of you.

• 𝗢𝗽𝗲𝗿𝗮𝘁𝗶𝗼𝗻𝗮𝗹 𝘀𝘂𝗽𝗽𝗼𝗿𝘁: Davinia for keeping our finances in order, Gonzalo for managing customer relations.

...and to everyone we worked with behind the scenes, thank you for your support.

If you’re curious about what we built in 2025, you can explore our projects at techdocs.studio/work:

Aligning Coiled’s documentation theme with their brand identity

Following the successful launch of Coiled’s new website, we developed a custom Sphinx documentation theme that aligned with their updated brand identity, ensuring a cohesive user experience across docs.coiled.io and the main marketing site.

Read case study

Custom Sphinx theme development for FiftyOne documentation

We upgraded FiftyOne’s documentation from Sphinx 3 to the latest version, created a custom theme aligned with the new Voxel51 brand guidelines, and implemented advanced search capabilities with PushFeedback integration for continuous improvement.

Read case study

From Webflow to Next.js: Creating a developer-first website for Coiled

Migrated Coiled’s website from Webflow to a modern, component-based static site generator, empowering their team to manage content like they manage code.

Read case study

Automating API reference generation from OpenAPI and GraphQL schemas

Migrated MONEI’s docs to Docusaurus v3, implemented cross-site search, and autogenerated consistent API documentation from OpenAPI and GraphQL contracts.

Read case study

Unifying Blue Robotics’ documentation with a custom Sphinx theme

Developed a custom Sphinx theme with Material design aesthetics, implemented multi-language support, and set up a custom CI/CD pipeline for version management across their documentation ecosystem.

Read case study

Here’s to 2026: more learning, more impact, and helping teams build documentation that scales!

— David

The waitlist just opened: https://tally.so/r/RGxzzJ

Join for early access and help decide what features to build first.

What’s the most annoying part of your screenshot workflow? 👇

An AI chatbot lets them ask in plain language and get instant answers from your existing documentation.

Here’s how to add Biel.ai to your documentation. This guide uses Docusaurus, but Biel.ai works with any static site generator.

Disclaimer: I built Biel.ai. It’s a paid service with a free trial.

Prerequisites

• Docusaurus site (existing or new)

• Node.js v18 or higher

• A sitemap for your docs site

Step 1: Create a Biel.ai account

Go to app.biel.ai and sign up. Follow the on-screen instructions to create your account.

Step 2: Create your first chatbot project

1. In your Biel.ai dashboard, click on the Projects tab at the top.

2. Click Create project.

3. Enter your project details:

   • Project name: Choose a unique name.

   • Sources: Select Sitemap and enter the sitemap URL of your Docusaurus site (e.g., docs.domain.com/sitemap.xml).

4. Click Save.

You’ll receive a unique Project ID. Keep this handy, as you’ll need it later.

Step 3: Install the chatbot

1. Install the Docusaurus package:

npm install docusaurus-biel

2. Add Biel.ai to your docusaurus.config.js file:

plugins: [
    [
        ‘docusaurus-biel’,{
            project: ‘<PROJECT_ID>’,
            version: ‘latest’
        }
    ]
],

Replace <PROJECT_ID> with the Project ID you received earlier.

3. Run your site locally to ensure everything is working properly:

npm start

The chatbot appears as a floating widget. Users can ask questions and get answers from your docs:

Step 4 - Customize your chatbot (optional)

You can tweak the chatbot’s appearance and behavior in the docusaurus.config.js file. For example, you can change the button text or adjust the chatbot’s position:

plugins: [
    [
        ‘docusaurus-biel’,{
            enable: true,
            project: ‘<PROJECT_ID>’,
            bielButtonText: ‘ASK AI’,
            buttonPosition: ‘center-right’,
            modalPosition: ‘sidebar-right’,
            headerTitle: ‘Biel.ai chatbot’
            buttonStyle: ‘dark’,
        }
    ]
],

For advanced customization options, such as adding an initial message, suggested questions, or further editing the style, refer to Customization.

What the chatbot conversations tell you

The chatbot tracks what users ask. This reveals gaps in your documentation.

If 50 people ask about webhook authentication but you don’t have a guide, that’s a signal to write one. The questions show what’s missing or unclear.

The AI only works as well as your documentation. Well-structured, comprehensive docs lead to better answers. Gaps lead to poor responses.

It’s right there in the docs. But the user searched “automatic notifications” and got nothing. The docs call it webhooks. The user doesn’t.

Traditional search works when users know the right terms. They usually don’t. They describe what they’re trying to do, not what the feature is called. Your docs could be perfect and users would still miss them because they searched the wrong word.

What we built

Over the past year, we’ve been building Biel.ai to solve this. It’s an AI chatbot that sits on your docs site and answers questions from your existing content. Think of it as ChatGPT, but trained on your product documentation.

Users ask a question in plain language. Biel finds the answer in your docs and responds. No keyword matching. No browsing through a sidebar hoping to find the right page.

What surprised us

Biel didn’t just help users find answers. It showed us what was missing.

The conversation logs revealed gaps we didn’t know about. Topics we assumed were covered but weren’t. Workflows that lived in Slack but not in the docs. Basic things nobody had written down.

We went from guessing what users needed to seeing it in the data. The chatbot became a feedback tool as much as a support tool.

Who this is for

If you maintain documentation for a technical product and your users keep asking questions the docs already answer, Biel can help.

It works with any static site generator. Setup takes about 10 minutes.

Want to see it on your docs? Send me a message at david@techdocs.studio with your docs URL and I’ll set up a demo.

PushPreview automates this. It builds a live preview for every pull request and posts the URL in a comment. Reviewers click the link, see the changes, and leave feedback on the actual content instead of fighting with build commands.

Here’s how to set it up.

Disclaimer: built PushPreview. It’s free for open-source projects and paid for commercial use.

Prerequisites

• GitHub repository with documentation

• Docs-as-Code setup (Markdown, static site generator)

• Docs build process (npm, yarn, etc.)

Step 1 - Create a PushPreview API Key

1. Sign up at app.pushpreview.com

2. Navigate to the Teams tab:

   

3. Under API keys, click Create API Key:

   

4. Copy the generated API key (you’ll need it next).

Step 2 - Configure a GitHub secret

Add your PushPreview API key to GitHub:

For a single repository:

1. Go to repository Settings > Secrets and variables > Actions

2. Click New repository secret

For multiple repositories (organization-wide):

1. Go to organization Settings > Secrets and variables > Actions

2. Click New organization secret

Add the secret:

• Name: PUSHPREVIEW_TOKEN

• Value: Your PushPreview API key

• Click Add secret.

Step 3: Add the GitHub Action

Create .github/workflows/pushpreview.yml in your repository:

name: PushPreview

on:
  pull_request_target:
    types:
      - labeled

jobs:
  preview:
    runs-on: ubuntu-latest
    if: github.event.label.name == ‘preview’
    steps:
      - uses: actions/checkout@v3
      - name: Comment
        run: |
          gh pr comment ${{ github.event.pull_request.number }} --repo ${{ github.repository }} --body “⚙️ Hang tight! PushPreview is building your preview. URL will be shared soon.”
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Set BASE_URL
        run: echo “BASE_URL=/github/${{ github.repository }}/${{ github.event.number }}/” >> $GITHUB_ENV

      - name: Setup environment
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Build site
        run: |
          cd docs
          yarn install --frozen-lockfile
          yarn build

      - name: Generate preview
        uses: PushLabsHQ/pushpreview-action@1.0.5
        with:
          source-directory: ./docs/build
          github-token: ${{ secrets.GITHUB_TOKEN }}
          pushpreview-token: ${{ secrets.PUSHPREVIEW_TOKEN }}

Modify the Setup environment and Build site steps to suit your static site build process:

- name: Setup environment
uses: actions/setup-node@v3
with:
  node-version: 18

- name: Build site
  run: |
    cd docs
    yarn install --frozen-lockfile
    yarn build

Ensure the source-directory in the Generate preview step points to your HTML files location post-build:

- name: Generate preview
  uses: PushLabsHQ/pushpreview-action@1.0.5
  with:
    source-directory: ./docs/build
    github-token: ${{ secrets.GITHUB_TOKEN }}
    pushpreview-token: ${{ secrets.PUSHPREVIEW_TOKEN }}

Save and push the updated pushpreview.yml to your repository main branch.

Note: Enabling pull request previews for Docusaurus? You will also need to follow an extra step. For more information, see Pull request previews for Docusaurus.

Step 4: Test It

1. Create a new pull request.

2. Add the preview label to the PR. (Don’t see the label? Create it).
   

   

3. Wait for the GitHub Action to run.

4. PushPreview comments on the PR with the preview URL:

   

5. Click the URL to see your changes live.

Troubleshooting

Preview fails to build: Check GitHub Actions logs. Verify your build command works locally. Confirm source-directory points to the right location.

No comment appears: Make sure the preview label is added. Check that PUSHPREVIEW_TOKEN is in GitHub secrets. Verify the workflow file is in .github/workflows/.

Preview shows 404: Check source-directory contains your built HTML files. For Docusaurus, make sure BASE_URL is set correctly.

No more building locally to review docs

Every PR gets a live preview automatically. No downloading branches. No local builds. Reviewers see the actual changes and focus on the content.

But setting them up is painful.

You end up running parallel infrastructure just for previews. Most solutions need full GitHub org admin access, and security teams won’t approve it. Open-source projects get charged per user or per build minute. External contributors either can’t trigger previews or they rack up huge bills.

What I built

PushPreview is a GitHub Action. Drop /preview in a comment. Get a preview URL.

No infrastructure to maintain. No admin access needed. Private and public previews. Auto-cleanup when PRs close.

For open-source projects, pricing is fair. No per-user charges, no surprises from external contributors.

Join the waitlist

Sign up at pushpreview.com. Questions? david@techdocs.studio

You find out when the next person hits the same broken example. Or worse, you don’t find out at all.

I built PushFeedback to fix this.

What It does

A feedback widget for documentation sites. Users click, highlight the problem, submit feedback.

You get it where you work: GitHub issues, email, Trello, wherever.

No more “there’s a typo somewhere in the docs” messages. They show you exactly where.

Beta access

I’m looking for technical writers and docs teams to test PushFeedback and help shape what gets built next.

What you get:

Free Starter license: unlimited feedback entries on one subdomain of your choice. Keep it after beta ends.

How to join:

Go to pushfeedback.com/beta and sign up.

You’ll get a confirmation email with setup instructions. Adding the widget takes 5 minutes - a few lines of code like Google Analytics.

What I need from you:

Use it. Tell me what works, what doesn’t, what’s missing.

Beta spots are limited. Sign up: pushfeedback.com/beta

- David

Widdershins converts OpenAPI to Markdown. Here’s how to use it.

Prerequisites

• Have a valid OpenAPI document.

• Have Node.js installed on your computer.

• Have basic command-line knowledge.

What’s Widdershins?

Widdershins is the open-source command-line tool we’ll use to convert the OpenAPI document to MarkDown. By default, Widdershins outputs MarkDown compatible with renderers such as Slate, ReSlate, and Shins.

Thanks to its customizable template system, we can customize the output to make it compatible with other static site generators such as Sphinx, Docusaurus or Mkdocs.

Installing Widdershins

Widdershins can be installed with NPM. In the command prompt, run the following command:

npm install -g widdershins

After the installation has been completed, you can verify Widdershins installation by running widdershins --version in the command prompt.

Parsing OpenAPI to MarkDown

Once Widdershins is installed, run the following command in the console prompt:

widdershins openapi.yaml -o openapi.md

Replace openapi.yaml with the path to your OpenAPI file in YAML or JSON.

The command stores the resulting MarkDown file as openapi.md.

Customizing the output with flags

Widdershins comes with other built-in options to configure the output. For example, the option omitHeader removes the YAML front-matter in the generated Markdown file.

👉 Check out the complete list of available options in the official docs.

In this example, we’re running the command from the previous step with the new option omitHeader:

widdershins openapi.yaml -o openapi.md --omitHeader

Using custom-defined templates

Suppose you want to change the output’s format, but you can’t achieve the level of customization you are looking for by just tweaking Widdershins CLI’s options. In this case, what we did is override the template Widdershins uses with a custom-defined template.

Here’s how:

1. Create a new directory named .widdershins. Inside, create a second folder named templates.

mkdir -p .widdershins/templates
cd .widdershins/templates

2. Copy the contents from the file main.dot in the folder you just created.

curl https://raw.githubusercontent.com/Mermade/widdershins/master/templates/openapi3/main.dot > main.dot

3. Edit main.dot with your favorite code editor. The template engine Widdershins uses is doT.js. This enables you to access any variable from the OpenAPI description, even vendor extensions or nested fields.

From my experience, getting started with the template engine could be tricky. Here’s a cheatsheet with the delimiters I’ve been using more to render and iterate through variables:

Evaluate

{{ var enums = []; }} // Executes the JavaScript code between the curly braces.

Print

{{=a}} // Renders the contents of the variable a
{{=a.b}}  // Renders the contents of the nested variable a.b

Conditional

{{? a }} hello {{?}} // If a is true, prints “hello”.
{{? !a }} hello {{?}} // If a is false, prints “hello”.
{{? a || b }} hello {{?}} // If a or b is true, prints “hello”.
{{? a && b }} hello {{?}} // If a and b is true, prints “hello”.

Iteration

{{~ alist:a}} {{= a }} {{~}}  // Iterates throught alist and prints every element.

4. Run the Widdershins CLI. In this case, add the option -u with the path to .widdershins/templates:

widdershins openapi.yaml -o openapi.md -u ./widdershins/templates

Next steps

Once the conversion works, automate it. Add Widdershins to your CI/CD pipeline so Markdown updates automatically when the OpenAPI spec changes.

For large API specs, the generated Markdown can be massive. Consider post-processing the output to split by endpoint or resource for better navigation.

Then configure your static site generator to handle the generated Markdown with proper styling and navigation.

I write about documentation systems, developer experience, and technical writing. Get new posts by email

Formatting slides takes forever. Choosing fonts, backgrounds, spacing between elements. You spend more time fighting with PowerPoint than writing content.

Marp converts Markdown files into presentation slides. Write in plain text, add formatting with simple syntax, export to whatever format you need.

Here’s how to use it.

Creating the presentation

No matter which tool you use to create the presentation, the first step is to know what you want to explain. Once you have the topic, open a new file with the extension .md. Then, write your notes for your presentation in plain text using Markdown syntax.

New to Markdown? Here is a cheat sheet with the most common annotations you’ll need to format titles, links, and tables.

Split into slides

Once you have all the content outlined, split the slides with the annotation ---. Here is an example.

# Slide 1

* Item 1
* item 2
* Item 3

---

# Slide 2

## Subtitle

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Export to different formats

Marp is the framework we’ll use to turn Markdown into a beautiful slide deck. Unfortunately, the tool is not available as a web application, so you’ll need a bit of experience playing with the terminal to use the tool.

For example, try to run one of the following commands to convert a Markdown slide deck into HTML, PDF, or PTTX. Replace PITCHME.md with your file name.

# Convert slide deck into HTML
npx @marp-team/marp-cli PITCHME.md --html

# Convert slide deck into PDF
npx @marp-team/marp-cli PITCHME.md --pdf

# Convert slide deck into PowerPoint document (PPTX)
npx @marp-team/marp-cli PITCHME.md --pptx

Do you want to preview the slides while you edit the contents? To run Marp in watch mode, run the following command instead:

npx @marp-team/marp-cli -w PITCHME.md

Then, open the resulting HTML file with your preferred browser.

If you use Visual Studio Code, you can preview the resulting slides as you write them with the Marp Extension for VSCode.

Adding a theme

Let’s change the style of the presentation. You can use one of the built-in themes. At the top of the MarkDown file, define which theme you want to apply using the directive theme. The file header should look like this:

---
theme: default
---

I’ve decided to go with the theme gaia for my presentation. Moreover, Marp provides other configurable directives that simultaneously apply to all the slides.

For example, I defined default values for the font color, background image, and enabled pagination for my presentation.

---
theme: gaia
color: #000
colorSecondary: #333
backgroundColor: #fff
backgroundImage: url(’https://marp.app/assets/hero-background.jpg’)
paginate: true
---

Styling a single slide

In some situations, you’ll only want to enable a directive for a given slide. You can apply directives selectively with comments. The next code snippet shows how to disable pagination for the first slide.

<!-- _paginate: false -->

# Slide 1

* Item 1
* item 2
* Item 3
---

Another common directive used per slide is _class. Each theme may come with a set of predefined classes. For example, the theme gaia introduces the class lead. When used, this centers the slide contents.

As you can see, the first slide used the class centering the title, whereas the second slide didn’t, and the contents appear aligned on top.

If you’re a skilled CSS developer, you might want to create a custom theme from scratch. John Wadleigh explains how to do it in Custom themes with Marp.

Working with images

A picture speaks 1,000 words. Most presentations include images, and Marp extends Markdown to define their size.

Add an image to your slides and change the size with width and height options.

![w:32 h:32](image.jpg)

You can also apply filters to images, such as adding opacity, a shadow, or even rotating the image. Here you have all the available predefined CSS filters supported. For example, the following snippet shows how to convert a photo to grayscale mode.

![grayscale](image.jpg)

Marp also brings the option to use images as backgrounds. Backgrounds also accept the same filters as images and additional options to position them.

By default, all background images fit the slide, but you can use the option auto to preserve the original size.

# The image fits the slide
![bg](image.jpg)

# The image is not rescaled
![bg auto](image.jpg)

# The image is scaled in a percentual value
![bg 80%](image.jpg)

The options left or right position the background to the specified side.

When this works

Marp works well for:

• Technical presentations with code examples

• Content-heavy slides without complex layouts

• Presentations you need to version control

• Slides that need to export to multiple formats

Marp doesn’t work well for:

• Highly visual presentations with custom layouts

• Slides with complex animations

• Presentations where design matters more than content

• Teams unfamiliar with Markdown or command line

The tradeoff

Writing slides in Markdown is faster for content. No fighting with layout tools. Version control works. Export to any format.

But there’s a learning curve. The command-line workflow isn’t for everyone. Complex designs are harder than drag-and-drop tools.

If you spend more time writing content than designing slides, Marp saves time. If you need pixel-perfect custom layouts, stick with visual tools.

In this article, we will break the Petstore example from the official OpenAPI documentation into smaller files.

A little side note before we start: This guide will be more helpful if you’ve documented an API project before by following the OpenAPI Specification. But don’t worry if you’re starting a new OpenAPI document from scratch. You’ll find a skeleton project ready to be adapted at the end of the post.

Prerequisites

This guide assumes that you’re familiar with the OpenAPI Specification 3.0 (previously known as Swagger). If you haven’t worked with the standard, I recommend you read first What is OpenAPI?. Then, try to write your first OpenAPI document.

Step 1: Reuse responses

It’s easier to start splitting an OpenAPI document if you’re already reusing schemas.

Say you have two endpoints: one listing all pets, another retrieving a single pet. Both return a Pet object.

paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        ‘200’:
          description: A paged array of pets
          [...]
          content:
            application/json:    
              schema:
                  type: object
                  required:
                    - id
                    - name
                  properties:
                    id:
                      type: integer
                      format: int64
                    name:
                      type: string
                    tag:
                      type: string
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        ‘200’:
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                  type: object
                  required:
                    - id
                    - name
                  properties:
                    id:
                      type: integer
                      format: int64
                    name:
                      type: string
                    tag:
                      type: string

Don’t define it twice. Following this example, define the schema once under components/schemas and reference it with $ref:

paths:
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        ‘200’:
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: “#/components/schemas/Pet”
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Step 2 : Reuse parameters

Now that you’re comfortable reusing schemas in the same file, let’s reuse the parameter petId from the operation showPetById.

As in the previous step, move the parameter from the path to the components/parameters section and use $ref to reference the component.

Here is an example:

paths:
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      parameters:
        - $ref: ‘#/components/parameters/petId’
[...]
components:
  parameters:
    petId:
        name: petId
        in: path
        required: true
        description: The id of the pet to retrieve
        schema:
            type: string

Step 3 : Import from separate file

By reusing definitions, your file should now be shorter, even before starting to split it. If you’re already pleased with the file organization, you can stop reading now... You’re still with me? Then let’s make our file more modular!

Do you remember the keyword we’ve been using to reuse content? $ref not only allows us to import objects from the same file but from other sources like a separate file or a remote URL as well.

Create a new file named schemas/Pet.yaml for the Pet schema. Then, move the definition to the new file. Here’s how the resulting file should look like:

// schemas/Pet.yaml
type: object
required:
- id
- name
properties:
id:
  type: integer
  format: int64
name:
  type: string
tag:
  type: string

Now, point $ref to the new file’s location.

// openapi.yaml
$ref: “./schemas/Pet.yaml”

Finally, do the same for the other objects that you might want to split into separate files.

Step 4: Move resources to a separate file

Until now, you’ve seen how to organize response objects and parameters. However, if the document defines several endpoints, you’ll likely still have a large file that’s difficult to maintain. Next, we’ll organize the resource paths into multiple files.

For example, you could create the file path/pet.yaml. This file should define all the available operations, which their associated parameters and responses for the endpoint /pets/{petId}:

//paths/pets.yaml
get:
  summary: Info for a specific pet
  operationId: showPetById
  tags:
    - pets
  parameters:
    - $ref: “../parameters/path/petId.yaml”
  responses:
    ‘200’:
      description: Expected response to a valid request
      content:
        application/json:
          schema:
            $ref: “../schemas/Pet.yaml”
    default:
      $ref: “../responses/UnexpectedError.yaml”

Then, import each path definition from the main OpenAPI document as we have been doing with the schemas and parameters.

//openapi.yaml
...
paths:
  /pets/{petId}:
      $ref: “./paths/pet.yaml

Finally, repeat the process for every other resource you want to import from a separate file.

Step 5: Organize with index files

Let’s go one step further! We can split up the project even more to achieve better organization. Our goal is to end up with a main OpenAPI document as tiny as the following one:

// openapi.yaml
openapi: “3.0.0”
info:
  version: 1.0.0
  title: Swagger Petstore
  description: Multi-file boilerplate for OpenAPI Specification.
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    $ref: “./paths/pets.yaml”
  /pets/{petId}:
    $ref: “./paths/pet.yaml”
components:
  parameters:
    $ref: “./parameters/_index.yaml”
  schemas:
    $ref: “./schemas/_index.yaml”
  responses:
    $ref: “./responses/_index.yaml”

To achieve this, create the following _index.yaml files:

• parameters/_index.yaml

• schemas/_index.yaml

• responses/_index.yaml

Then, move to every file its definitions. For instance, ./schemas/_index.yaml for the Petstore example would look like:

Pet:
  $ref: “./Pet.yaml”
Pets:
  $ref: “./Pets.yaml”
Error:
  $ref: “./Error.yaml”

Step 6: Bundle back to one file

Some of the OpenAPI based tools support only a single file as an input. To continue using the spec with those tools, we’ll compile all the different files we’ve created with the command-line tool swagger-cli.

1. Open a new terminal. Then, install the package swagger-cli globally:

npm install -g swagger-cli

2. Run the command to merge all the files into one:

swagger-cli bundle openapi.yaml --outfile _build/openapi.yaml --type yaml

3. If everything goes well, you should see a single OpenAPI file compiled under the _build directory.

Putting all together

Splitting a large OpenAPI spec into multiple files makes it more maintainable. In my experience, it also makes other developers more willing to contribute. When the project is well organized, proposing changes feels less intimidating.

Here’s the repository with the Petstore example divided into multiple files: openapi-boilerplate. Feel free to reuse it as a starting point.

I write about documentation systems, developer experience, and technical writing. Get new posts by email