Rework Markdoc info hierarchy #7744
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
1 Ignored Deployment
|
|
@bholmesdev the table of contents does indeed look much nicer! Just because the diff is going to look terrible here, and not really reflect what you actually did, is the section on Partials the only new/changed content (other than reordering?) This will save me a bunch of close reading trying to figure out what content actually did change, and will also help the translators who will have to make sense of this PR when they update in all the other languages. 😄 |
|
Yes, apologies! Let's get the Partials PR reviewed first, then rebase this PR once it is merged. That way we don't have to untangle new content from reorganization. |
sarah11918
added
the
improve or update documentation
bholmesdev
force-pushed
the
refactor/markdoc-toc
branch
from
3d3864d to
14550bb
Compare
|
@sarah11918 Okay, rebased and ready for review! |
|
Great! Assuming this is just reorganization of existing content for flow, this now should be an easier read! |
|
|
||
| For example, the heading `### Level 3 heading!` will pass `level: 3` and `id: 'level-3-heading'` as component props. | ||
|
|
||
| ### Custom image components |
There was a problem hiding this comment.
Just a note for translators: this heading has changed from "Custom image components in Markdoc" to just "Custom image components" It's more than just moved!! 💜
| ``` | ||
|
|
||
| ### Markdoc config | ||
| ## Advanced Markdoc configuration |
There was a problem hiding this comment.
Note for translators: this heading has changed! Not just moved!
It was previously (lol) "### Markdoc config" (line 470 in English) nested under "## Markdoc config"
We heard you liked Markdoc config, so we put some Markdog config in your Markdoc config...
There was a problem hiding this comment.
The reorganization looks fantastic @bholmesdev !
I left a couple of notes for translators to indicate when a heading actually changed content (vs just moving around). You can ignore those, that's just for their convenience.
I also left a comment about a "read more" line that I think got missed or errantly moved in the shuffle. Pretty sure that was an unintentional change and I identified where it should end up instead.
The only thing about the reorganization itself I could see shuffling:
Pass Markdoc variables and Access frontmatter from your Markdoc could go much higher, I'd argue maybe even under Usage?
This seems like a more common use case, and related to just "writing Markdoc", enough so that it feels like it could go right above using components. Also noting that the Access frontmatter is very related to the usage example showing accessing frontmatter variables. So, if you think those two sections show reasonably common use cases, I'd throw them up at the top there. If you think they are low-usage things that aren't all that common, then no issue keeping them lower. They just feel much more related to writing your Markdoc to me.
In any event, whatever you decide, this is a fabulous change! 🫡
|
Thanks @sarah11918! Totally agree with that suggestion to move variables and frontmatter just after "usage." I also realized the "markdoc language server" was buried at the end, when it really belongs under Installation. I actually discovered we have two competing sections for editor configuration! I resolved the differences in this commit. I also removed the lengthy explanation of the extension config file, just highlighting the parts that are relevant. |
| @@ -75,18 +75,29 @@ export default defineConfig({ | |||
| }); | |||
| ``` | |||
|
|
|||
| ### Editor Integration | |||
| ### VS Code Editor Integration | |||
There was a problem hiding this comment.
Also note to translators: This new section is a combination of the older Editor Integration and #Markdoc langauge server. They have both been combined into this one!
sarah11918
added
the
Merge Queue
…tro#7744 Signed-off-by: Thomas Bonnet <[email protected]>
* i18n(fr): Updating `guides/integration-guide/markdoc.mdx` from #7743 Signed-off-by: Thomas Bonnet <[email protected]> * i18n(fr): Updating `guides/integration-guide/markdoc.mdx` from #7744 Signed-off-by: Thomas Bonnet <[email protected]> * i18n(fr): Fix link L232 Signed-off-by: Thomas Bonnet <[email protected]> * Update src/content/docs/fr/guides/integrations-guide/markdoc.mdx Co-authored-by: pioupia <[email protected]> * Update src/content/docs/fr/guides/integrations-guide/markdoc.mdx Co-authored-by: pioupia <[email protected]> --------- Signed-off-by: Thomas Bonnet <[email protected]> Co-authored-by: pioupia <[email protected]> Co-authored-by: Yan <[email protected]>
Description (required)
Before | After
Related issues & labels (optional)