Astro-MDoc

Inspiration

I like playing with frameworks and i want to achieve best SEO score for my sites/projects that i make which makes Astro as a prefered choice for me, but Astro shines at SSG and recently team Astro+QwikDevs created a plugin/Integration which uses Qwik's resumability in Astro projects which makes Astro really shine at SSR too

The requests from Astro Community for adding SSR support for their official MarkDoc Plugin/Integration is My Inspiration to create this Plugin

What it does

Astro has an Official MarkDoc Integartion, from the README's usage the Astro Markdoc plugin can only create Docs by reading content in src/content/ and The NEXTJS-MarkDoc plugin supports SSR rendering, My Goal is to create a plugin/Integration for Astro that has similar experience for NextJS users who are migrating their site to Astro should be convenient

This Integration Reads the partial MarkDoc Configs from multiple files and folder to create an Isolated MarkDoc Config file at buildtime.

The plugin should read fom the User's project's src/markdoc/ folder to create a markdoc Config and this approach is an Inspiration from NextJs-MarkDoc plugin and i wish to create same, so that user can split his large config in multiple files so that it would be convenient to maintain and manipulate Configs easily

Then the Plugin will create a config and Using Vite Virtual Module it creates an importable config file which is used in later points of the Project

AstroComponents are what the final renderable components for Astro, Astro supports multiple view frameworks like react, vue, svelte, etc.., and any React or Vue or Svelte component should be converted to AstroComponent to render it

Astro has some APIs for their Internal use to create AstroComponents which can be subjected to change at any point of time and these are not Documented anywhere! like AstroComponentFactory, renderComponent, render, renderTemplate, renderHeadAndComponent etc.., are some internal apis that Astro uses to create AstroComponents from their components(maybe React components or Vue Components or Svelte components or Lit Components etc..,) and I should too use the same approach, The user can pass their component at config's render which takes Imported object instead of string like NextJS Plugin's render and converts them into AstroComponent at runtime and return responses in the expected way, this project is Highly dependent on Dynamic Imports and Internal Apis of Astro which is a bit complex

render markdoc source from

---
import { MarkdocRenderer } from 'astro-mdoc/src/virtual/imports.js';
const Renderer = await MarkdocRenderer({ source: "your markdoc source"})
---
{
    Array.isArray(Renderer) ? (
        Renderer.map(Render => <Render />)
    ) : (
        <Renderer />
    )
}

How we built it

this plugin is built for Astro framework so we Astro as a peer dependency and GrayMatter which is used to parse MarkDoc Frontmatter and etc..,

Challenges we ran into

The Integration should read MarkDoc Configs from users project and for this NextJS-Markdoc plugin uses Webpack's module resolution to solve these imports but Astro uses Vite which has no built in functionality to support it which made me to use a different approach, i googled about it but haven't found any resource to solve it :( which made me to force use node:url and node:fs to solve this issue and which is working as expected, and to solve SSR rendering of astro components by Dynamic Imports are two 2⃣ most challenges i gone through this project

Accomplishments that we're proud of

It finally renders things as expected and got around 160 downloads so far which is i am proud of

What we learned

learnt about Vite vitrual modules, Astro Internal apis and declare module and GrayMatter dependency

What's next for Astro-MDoc

There are couple of bugs i found in the project and need to polish the code to improve code readability and add docs and tests for project and imporve README of the project

Built With

• astro