Provide Markdown based API documentation

[gebeer]

Hi all,

I would like to propose a different format for https://processwire.com/api/ref/

The PW docs should be provided as markdown.

Reasons:

• much easier to parse for machines
• easier to feed as context to AI assistants

Most of popular modern frameworks / libraries (laravel, whole node ecosystem, etc.) have their docs in markdown nowadays. And I think it is exactly for the reasons mentioned.

Me and also others here like @wbmnfktr are having a hard time providing meaningful context to AI assistants in IDEs like Cursor, Windsurf etc. Once those assistants have good context, they do an excellent job with PW specific code. But currently there is a lot of manual effort required to provide this context.

ProcessWire would be more accessible to a wider range of users if development could be assisted by AI in an efficient way. 

I created markdown docs with python mkdocs at https://gebeer.github.io/mkdocs-processwire/ 
WARNING: this is in it's early stages and far from complete/perfect. It is merely for demonstration purposes atm and needs a lot of polish regarding structure, index pages for each class etc.

I am using a separate local repo for scraping the API docs and parsing them to markdown.

The whole process of scraping/parsing/deploying still involves manual steps (though those could be automated). And it needs to be repeated at least for every master release of PW.

So I would prefer if @ryan could produce the API docs in markdown in the first place.

Your feedback / opinions would be much appreciated.

Cheers

 

 

[gebeer]

Just to clarify: obviously, the public facing API docs will still be in HTML, like at https://gebeer.github.io/mkdocs-processwire/ 

But the underlying files are all neatly in markdown in a separate repo.  

[bernhard]

+1

Docs in markdown have been working great for me. All my module docs are markdown, so they are part of the repo (could be another repo as well, as images for example bloat the module code, which is not ideal).

I'm using RockFrontend's dom tools to enhance the markdown docs with some special features. That makes it possible to have working forms on my docs for RockForms, for example:

https://www.baumrock.com/en/processwire/modules/rockforms/docs/

## Working Example

In this example we will build the following form.

[rockforms=Quickstart]

Or another example is rendering code blocks and showing copy buttons. In markdown it's just a plain code example, on the HTML page it's an interactive element with nice labels etc:

## Example

This example shows how you can make every required field's label bold and add the note `optional` to every field that is not required. Note that NetteForms uses the terms `label` and `caption` for field labels.

[rockforms=Optional]

`label: /site/ready.php`
```php
$wire->addHookBefore(
  "RockForms::renderField",
  function (HookEvent $event) {
    // get the field that is rendered
    // in netteforms its called "control"
    $control = $event->arguments(1);

    // make required fields bold
    if ($control->isRequired()) {
      $control->getLabelPrototype()->addClass('uk-text-bold');
    }
    // add optional note if not required
    else {
      $renderer = $event->arguments(0);
      $label = $control->label->getText() . " <small>(optional)</small>";
      $control->setCaption($renderer->html($label));
    }
  }
);
```

 

[dotnetic]

I think this is a good idea. While the docs are not in markdown, you could use https://context7.com/?q=processwire as an MCP Server for your coding assistant (like RooCode, Cline, Windsurf, Cursor, etc) for context. Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. Paste accurate, relevant documentation directly into tools like Cursor, Claude, or any LLM.

[gebeer]

5 hours ago, dotnetic said:

I think this is a good idea. While the docs are not in markdown, you could use https://context7.com/?q=processwire as an MCP Server for your coding assistant (like RooCode, Cline, Windsurf, Cursor, etc) for context. Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. Paste accurate, relevant documentation directly into tools like Cursor, Claude, or any LLM.

Actually, Context7 was what made me start this thread. Someone has already submitted the PW repo to their scraper. But the resulting snippets are mostly garbage: https://context7.com/processwire/processwire

Now why is that?

They do not scrape the very well documented PHP source files. If docs were in markdown, they would.

I tried the MCP and it didn't have context for simple things like WireHttp.

Does anyone know what tooling is currently used to create the PW API docs, phpDocumentor, phpDox, ApiGen or something different? 

[interrobang]

14 hours ago, gebeer said:

Does anyone know what tooling is currently used to create the PW API docs, phpDocumentor, phpDox, ApiGen or something different? 

I think the docs are generated with a custom module: https://processwire.com/blog/posts/processwire-3.0.41-and-a-look-at-api-explorer/

[monollonom]

(I’m not using AI assistants to code but) if this demand could go through the financial support of ProDevTools/@ryan that would be great

[BrendonKoz]

1 hour ago, interrobang said:

I think the docs are generated with a custom module: https://processwire.com/blog/posts/processwire-3.0.41-and-a-look-at-api-explorer/

Yup. From https://processwire.com/store/pro-dev-tools/api-explorer/

Could check and see what methods are hookable to potentially generate markdown instead of HTML. Current licensing seems to indicate that using it is solely for the purpose of the license holder though, so generating Markdown from it would be usable by the developer, but not shareable. Until or unless Ryan can consider if he would also not mind generating Markdown with the official docs, it may be a more practical option for those looking to do it now.

[gebeer]

Thank you all for clarification.
I am doing some tests atm with phpDocumentor to see if it can give decent results.

Guess the PWDOC parser is custom magic inside https://processwire.com/store/pro-dev-tools/api-explorer/ 
Let's see if we can do without or reengineer it...