Official way to use Markdoc on the frontend without a framework.

[zeel01]

I'm evaluating using Markdoc to improve an existing documentation site that currently uses plain HTML files for docs. The site uses a PHP backend, so I can't run Markdoc there. I'm not all that familiar with React, but it looks like it can run everything on the frontend? Regardless, I can't rebuild this site in React even if I wanted to.

What I did do, was use Browserify to bundle the Node package for use in the the browser and... it works! Though it makes the code a little messy to debug, it's not too bad and I haven't encountered any issues with this approach.

Question is, is there a better/simpler way to do this? Obviously this way, if I update Markdoc in the future I'll need to re-browserify it.

So either:

• I would love to know if I'm just dense and there's actually a better way to include this for use on the frontend (that doesn't involve any UI frameworks).
• It would be really cool if Markdoc came with a browser-ready build in the release.

[matv-stripe]

@zeel01 Hi!

Currently we use esbuild to output a ESM module for Markdoc. It is possible to run everything on the frontend without using React.

The most common use cases with Markdoc on the frontend usually involve using it with some sort of build system. Could you share more about your use case and how you are using Browserify? It seems possible to set up a build system with Browserify so that you can keep with the most up to date version of Markdoc.

Are you expecting to be able to do something like:

<script src="https://unpkg.com/@markdoc/markdoc@0.1.2/dist/index.js"></script>
<script>
const ast = Markdoc.parse("## header")
</script>

?

[zeel01]

I'm using Browserfy in the most simplistic way - I just created a JS file like:

// src/markdoc.js
window.Markdoc = require('@markdoc/markdoc');

then ran Browserify on it from the command line, and include the output script:

<script src="dist/markdoc.js" type="text/javascript"></script>

This approach works, I just have to re-bundle it if there is an update. Since I don't have anything else being built for this site, there isn't much point in creating a build script just for this one thing.

This might already be the best approach, but I was wondering if there was something I was overlooking. Plus, I know that using Browserify isn't necessarily perfectly reliable: There may be features that don't work correctly that I haven't noticed, and future versions could break it if this isn't a "supported" method of using the library. So it would be nice if there were an officially supported method for using it this way.

My goal in most situations is minimal framework, minimal dependencies, minimal build steps.

[shivanan]

Is there a way to do this? Ideally I want to just run some client side script that can load .md files from the server and render them dynamically. I don't want to run a separate server for documentation - and since we can't generate them statically, would this approach work?

[zeel01]

I'm not sure if anything has changed since June that would impact this. A quick look over the release changelogs and I don't see anything that that seems relevant.

[nkohari-stripe]

If you want to run Markdoc on the browser, the easiest approach is what @matv-stripe mentioned: using esbuild (or another transpiler) to transform the Markdoc files into JavaScript files which you then publish to a CDN.

If you want purely static content, you can also render Markdoc to HTML which you can load directly in the browser, and not run Markdoc at all client-side. There isn't an official way to do this -- what you're really talking about is using Markdoc as part of a static site renderer, which is out of the scope of the project. It's definitely feasible to use it with a static site renderer like Gatsby (using the third-party gatsby-transformer-markdoc plugin, for example), or you could write your own build script which generates the HTML from your Markdoc files.

[zeel01]

Yeah, not really looking for static. Just the most reliable and most well supported way to use it on the frontend without React. I haven't tried esbuild yet, but I assume the results are similar to browserify. Which works, but just adds a build requirement to an app that otherwise didn't need any build steps at all. I had hoped when I originally asked this question that the answer would be that I was just missing something, but I think the answer is "no, that's right, you will need to build it with... something."

Disappointing, but not the end of the world.

[nkohari-stripe]

If you're willing to run Markdoc on the client, you could also publish your .md files directly to a CDN, and then load and render them to HTML on the client. That'd be less performant, and users would see a short delay as the browser loaded and rendered the Markdoc content, but that might be acceptable for your site!

[andreyvit]

Hey, you can use Markdoc + Next.js static build to generate a set of HTML pages from a Markdoc site, which you can then serve with a web server / output with PHP / whatever. (I'm personally using Go, and do not want to host any server-side JS in production either.)

Basically, what I did was use Tailwind UI's documentation template (which is already set up with Next.js and Markdoc), and then adding output: 'export' to nextConfig in next.config.mjs and passing mode: 'static' to withMarkdoc.

Hope this helps.

[mustfaibra]

@andreyvit Can you please add more details on how to add the output with export value?
An example or snippet would be perfect.

[sanabel-al-firdaws]

if you don't mind having a build step you can always use something like Astro

the Markdoc workflow is smooth and i like it the build takes less than a minute so i don't mind

the only problem is you have to use .mdoc extension

i just add a renamer script to rename all md files to that extension

[kkukshtel]

Watching the presentation here:
https://www.writethedocs.org/videos/prague/2022/two-years-of-markdoc-what-we-ve-learned-about-balancing-developer-and-author-ex-ryan-paul/

There is mention of a hosted markdoc editor using Monaco (22:50) - has there been any new work on that?