Markdoc's Future

[louiss0]

Body

I have tried out remark so far and have found some problems with it as listed in Issue 6829 I'm not sure if this will be the primary way of doing things going forward but I hope it is. I have the following questions.

• Is Markdoc going to be content only.
• Are you guys going to find a way to make it to add loops to it.
• How is the choice between Prism and Shiki going to be implemented.
• Can we get some default tags like switch, it's implemented in the docs Markdoc Switch
• Is there going to be an improvement on Markdoc errors.
  • They are awful, terrible.
• Is remark going to work with Markdoc if so how?

[bholmesdev]

I can answer these rapid fire:

1. Markdoc is planned to be content collection exclusive, yes!
2. We've messaged the Markdoc team about for loops. There are deep, historic reasons that they removed loops from their implementation. I'm still wrapping my head around these concerns to see if we also need to worry about them.
3. Prism and Shiki should be implemented as transforms on code nodes. The implementation is still in-progress.
4. I think we will leave custom tags like these to userland for now, since the if block addresses the same use case today.
5. Errors are now improved with the latest validation fix!
6. As far as I can tell, Remark is incompatible with Markdoc's transform pipeline. There isn't a clear way to map one to the other, so my instinct is to avoid complex mapping layers. We need to decide best practices for Markdoc transforms since documentation around the topic is new and not especially beginner-friendly.

[louiss0]

I can answer these rapid fire:

1. Markdoc is planned to be content collection exclusive, yes!
2. We've messaged the Markdoc team about for loops. There are deep, historic reasons that they removed loops from their implementation. I'm still wrapping my head around these concerns to see if we also need to worry about them.
3. Prism and Shiki should be implemented as transforms on code nodes. The implementation is still in-progress.
4. I think we will leave custom tags like these to userland for now, since the if block addresses the same use case today.
5. Errors are now improved with the latest validation fix!
6. As far as I can tell, Remark is incompatible with Markdoc's transform pipeline. There isn't a clear way to map one to the other, so my instinct is to avoid complex mapping layers. We need to decide best practices for Markdoc transforms since documentation around the topic is new and not especially beginner-friendly.

Without Remark there is no magic. Tags do a lot but remark was good for page formatting now everything has to be done manually.

So what about the prompt for a markdoc config file? We need that. In fact, it's better to just create it along with the integration. I could do a PR. Thanks for the answers.

[bholmesdev]

Agreed, creating the file when running astro add markdoc would be a nice addition! This would mimic our astro add tailwind today, which generates a tailwind config. Happy to review a PR if you want to contribute.

I also understand the concern around remark. I think this is the toughest hurdle. If there's shared community demand, we can investigate code gen and documentation options to convert remark plugins to something Markdoc-compatible.

[louiss0]

Agreed, creating the file when running astro add markdoc would be a nice addition! This would mimic our astro add tailwind today, which generates a tailwind config. Happy to review a PR if you want to contribute.

I also understand the concern around remark. I think this is the toughest hurdle. If there's shared community demand, we can investigate code gen and documentation options to convert remark plugins to something Markdoc-compatible.

Remark plugins like remark-footnotes were good for automating lots of stuff. I'm not sure you're willing to recreate that tooling but people will need it. I won't but there has to be a way to give back some of what devs lose by using Markdoc. That is what I care about.

I suggest seeing how some remark plugins work and attempting to replace some of them with either plugins or Components that can be used as tags.

[louiss0]

When is Markdoc coming out of the experimental phase?

[bholmesdev]

Undetermined at the moment! We'll share on our public roadmap once we have an official timeline

[louiss0]

Markdoc has come out with a language server.

It supports configuration through something called an array of JSON. in a markdoc.config.json file. Each object in the JSON array is a custom configuration.

	{
        "id": "project",
        "path": "project/src/content",
        "schema": {
            "path": "project/markdoc.config.mjs",
            "type": "node",
            "property": "default",
            "watch": true
        }
    }

I tried it out it does not seem to work for some reason.
Anyway test it out here

[bholmesdev]

Woo, it's finally here! Will need to do some digging on how to get this working, seems like there's some involved steps. Will add to the roadmap

[louiss0]

Woo, it's finally here! Will need to do some digging on how to get this working, seems like there's some involved steps. Will add to the roadmap

There is another issue regarding markdoc here

[bholmesdev]

Sorry, but can you avoid replying with unrelated issues? We scan our issue logs and triage appropriately, so don't worry about us finding or tracking these! Thanks

[louiss0]

Sorry, but can you avoid replying with unrelated issues? We scan our issue logs and triage appropriately, so don't worry about us finding or tracking these! Thanks

It takes a long time for things to change. I guess I'll wait then.

[louiss0]

Can you tell me how extends works?

[louiss0]

You need to tell people in the future that if they want to pass in the primary attribute they will need to pass primary: true.

The primary attribute is what you pass in after the tag name without symbols or key=value pairing.

{% abbr "Hyper Text Markup Language" %}

This is how it's configured

primary: {
            type: String, 
            render:true
          },

[louiss0]

I thinking about creating a library that has lots of tag schemas that render html components. Do you want to do that? I dont mind doing that myself then passing it on to you. markdoc does not render html tags by default and provides no tags for them.

[louiss0]

I created a new library that includes all HTML schemas that will be needed in Markdoc. It's called Markdoc HTML Tag Schemas.
It's a library that is filled with all the schema that are fit for writing HTML that is fit for articles. Here are the docs. It's on npm if you want to use it in a markdoc project.

  npm i markdoc-html-tag-schemas

To configure it all you need to do is.

import { defineMarkdocConfig,} from '@astrojs/markdoc/config';

import { markdocHTMLTagSchemas } from 'markdoc-html-tag-schemas';

export default defineMarkdocConfig({
  extends: [
    markdocHTMLTagSchemas()
    ],
});
 

Here is a list of all the HTML tags that are supported by this library.

• a
• img
• br
• hr
• video
• audio
• iframe
• source
• picture
• time
• span
• address
• track
• ul
  • li
• blockquote
• details
  • summary
• dl
• colgroup
• col
• p
• sup
• sub
• small
• wbr
• del
• ins
• cite
• code
• samp
• mark
• q
• kbd
• bdo
• bdi
• data
• dd
• span
• time
• dfn

[jasikpark]

the good version of amp-html xD

[louiss0]

I'm hoping to get only two features now.

• Automatic reload for markdoc config.
• Markdoc config generation

Other than that I have nothing else to ask for. I guess there is the problem with having to specify attributes along with registering the component.

[louiss0]

This sucks to write a library for months only to find out that it's useless after months of creating it's sad. I guess I should have asked before doing this. I guess this means that tags are only useful as components. With that being the case what about support for content projection?

[bholmesdev]

I know, I felt terrible writing this realizing I missed your message in June. I'm curious what you mean by "tags are only useful as components" and "support for content projection?" Both of these could be interesting additions

[louiss0]

What I meant by "tags are only useful as components" is that the allowHTML: option is will make it so that using tags to create HTML is useless. You would only register tags when you need to use components in Markdoc Pages.

What I meant by "support for content projection?" is that you can't use the slots of components to render anything in markdoc.

Let's pretend this component is called Example and I registered it as a tag with the same name.

 
 <div>
{Astro.slots.render("default")}
 </div> 

The content passed to this tag will not be rendered by astro.

    {% example %}
       I'm the example
    {% /example %}

I could be wrong about this one but I bet you can't do this.

This is called Example component again

<div>
{Astro.slots.render("first")}
 </div> 
 <div>
{Astro.slots.render("second")}
 </div> 

    {% example %}

    {% slot name=first %}
       I'm the example
    {% /slot %}

     {% slot name="second" %}
       I'm the example
    {% /slot %}
       
    {% /example %}

[bholmesdev]

Gotcha. On the first point, I'll admit this was an intention for tags; we want to make tags the way to match up Astro components, ideally even easier than it is today with future enhancements. Not too worried if allowHTML is preferred over tags for the HTML element case.

As for the latter, are you implying allowHTML makes this no longer feasible? This ideally should be supported but I'd need a to see a test case

[louiss0]

I'm not implying that allowHTML doesn't make anything feasible. I'm just saying that people will rarely use the tags. In fact, people will rarely add anything other than the allowHTML: true.

[louiss0]

In the future can the markdoc scaffold come with the config for the Markdoc Language Server? I tried to configure it myself and decided to quit. I know the tool is not mature but. I was 100 percent sure that I did it right.

[bholmesdev]

Yeah, that's the second complaint I've heard so far. Was definitely rooting for it but the tool isn't working how I'd expect it to. I'll need to follow up with the team on how to use the config file. I'll admit I'm pulled into another project at Astro for the next month or so and may be slow to respond here!

[louiss0]

I'll have to talk about this with the team then.

[louiss0]

Today I just found out how to get the language server to work markdoc.

"path": "src/content",
    "schema": {
      "path": "markdoc.config.mjs",
      "type": "esm",
      "property": "default",
      "watch": true
    },

You must specify the "type" as "esm". You use an absolute path to the folder you are using. The schema.path is where the config is.

The language server does not respect extends at all.

Clone this project and you'll see what I mean. https://github.com/louiss0/dummy-markdoc-2

[louiss0]

Am I allowed to recommend my library?

[louiss0]

Markdoc Language Server doesn't respect extends:[] I don't know what you can do but I leave it up to you.

[bholmesdev]

Yeah that's unfortunate. The answer there is to bring extends into the Markdoc standard. I spoke with the maintainers and they like the API design! Deserves an issue on their github, I'll make a note

[bholmesdev]

@louiss0 Oh, what is the library? Does it help with Markdoc configuration?

[louiss0]

The markdoc-html tag-schemas library.

[louiss0]

I did the PR here

[louiss0]

I just found out what the route functionality is for
Look.

[louiss0]

There is nothing much to discuss anymore. Overall I'm happy about this discussion. I think I got everything I want from all of this.
Please don't forget to look into the extends problem. I hope people may consider using my library but things are what they are.
I'm done for now I now want to look into starlight