feat(md,wit): format WIT and nested code inside markdown files by mkatychev · Pull Request #379 · bytecodealliance/component-docs

mkatychev · 2026-10-06T22:50:49Z

!!WIP!!

WIT formatting:
topiary fmt ./**/*.wit

markdown formatting (only formats WIT, toml codeblocks):
topiary fmt ./**/*.md --skip-stage host --skip-language rust

mkatychev · 2026-10-06T23:00:08Z


 world target-world {
-  include wasi:http/proxy@0.2.3;
+    include wasi:http/proxy@0.2.3;


up to us what indentation we prefer, this can be set in .topiary/languages.ncl similar to the indent key here:
https://github.com/topiary/topiary/blob/c72efbfd164f98e5d2fab70a7c984280e0a90378/topiary-config/languages.ncl#L284-L294

mkatychev · 2026-10-06T23:00:25Z

+  (code_fence_content) @injection.content
+  ; mdBook inline macro
+  (#not-match? @info ".*(nofmt|rust).*")
+  (#not-match? @injection.content "\\{\\{\\#include")


used to skip mdbook directives

mkatychev · 2026-10-06T23:00:54Z

 A WASI 0.2 read call returned a single `input-stream` resource and surfaced terminal errors only as you consumed it. WASI 0.3 splits those concerns: the call returns a `stream<u8>` for the data and a `future<result<_, error-code>>` for the outcome, packed into a tuple.

-```wit
+```wit nofmt


nofmt is picked up by this query to skip WIT fragments:

component-docs/.topiary/queries/injections.scm

Line 6 in 969ae33

(#not-match? @info ".*(nofmt|rust).*")

mkatychev · 2026-10-06T23:01:23Z

    include wasi:cli/imports@0.2.0;
-
    export add;
-}


up to us if we want to preserve double newlines between certain items

Yeah let's have newlines between this, but only for worlds? I like the idea of separating the imports, includes and exports in a world declaration

mkatychev · 2026-10-06T23:06:06Z

Neat thing about diff grammar is that technically so adding a language hint can actually allow one to format it if the code fence start was changed to something like this by formatting new and old state separately:

```diff wit
world app { 
    import calculate; 
+   export wasi:cli/run@0.2.7; 
} 
```

component-docs/component-model/src/tutorial.md

Lines 128 to 133 in 969ae33

    
           ```diff 
        
           world app { 
        
               import calculate; 
        
           +   export wasi:cli/run@0.2.7; 
        
           } 
        
           ```

…ources/rust.md --skip-stage host --skip-language rust`

mkatychev · 2026-10-06T23:14:28Z

+      },
+      queries.injections.source.path = "queries/injections.scm",
+    },
+    wit.indent = "   ", # 4 spaces


The repo has a mix of 2 and 4 space indentation for WIT and this helps align it.

mkatychev · 2026-10-06T23:20:25Z

rustfmt canll be used for the rust formatting backend once topiary/bud#8 is implemented (as well as gofmt for go codeblocks and whatever else):

component-docs/component-model/src/language-support/using-wit-resources/rust.md

Lines 243 to 245 in 39e62fc

    
               ```rust 
        
               impl docs::rpn::types::HostEngine for MyHost { 
        
                   fn new(

mkatychev · 2026-10-06T23:30:48Z

 An `enum` type is a variant type where none of the cases have associated data:

-```wit
+```wit nofmt


nofmt will eventually be removed once hideline fragments are properly handled in topiary:

Suggested change

```wit nofmt

```wit,hidelines=!!!

!!! interface foo {

vados-cosmonic · 2026-10-07T15:22:40Z

+   enum op {
+      add,
+   }
+   eval-expression: func(op: op, x: u32, y: u32) -> u32;


It would be nice if we defaulted to a space between items inside an interface.

Should this apply to worlds as well? We can do only a subset of each as well:
https://github.com/bytecodealliance/tree-sitter-wit/blob/f777cdbe11281ccc68ffa30bd7ea34cdf4ddbec6/grammar.js#L139-L146

world_definition: ($) => choice( $.export_item, $.import_item, $.use_item, $.typedef_item, $.include_item, ), // ... _interface_definition: ($) => choice( $.use_item, seq(optional($.external_id), choice($.typedef_item, $.func_item)), ),

# Fix WIT formatting errors encountered in markdown References bytecodealliance/component-docs#379 bytecodealliance/tree-sitter-wit#33 ## Description Handle mdbook as well as newline separation between various WIT definitions * added new WIT test case * fix(wit): added new queries to handle edge case * fix(wit): inline statement node * revert(config): pin WIT gramar * revert: errant changes * Auto-publish releases to crates.io (#1344) * Auto-publish releases to crates.io * Update MAINTAINERS.md * Update CHANGELOG.md * log(config): add callout when failing to copy queries during fetch (#1343) During `topiary prefetch`, nonexistent files are not called out when copying thus returning unclear errors: ``` ● I/O Error ├ topiary-cli/src/config.rs:136 │ ● Error Fetching Language: We encountered an io error: No such file or directory (os error 2) ├ topiary-cli/src/config.rs:136 ╰ topiary_config::error::TopiaryConfigError::Fetching(Io(Os { code: 2, kind: NotFound, message: "No such file or directory" })) ``` --------- Co-authored-by: Christopher Harrison <Xophmeister@users.noreply.github.com> * fix(config): update WIT grammar sha * fix(ci): prefetch markdown --------- Co-authored-by: Christopher Harrison <Xophmeister@users.noreply.github.com>

mkatychev added 4 commits October 6, 2026 17:48

feat(md,wit): format WIT and nested code inside markdown files

79d151e

test: initial WIT formatting: topiary fmt ./**/*.wit

b8d0577

test: intial markdown formatting pass

6c5c53d

test: markdown formatting callouts

969ae33

mkatychev commented Oct 6, 2026

View reviewed changes

test: `topiary fmt component-model/src/language-support/using-wit-res…

39e62fc

…ources/rust.md --skip-stage host --skip-language rust`

mkatychev commented Oct 6, 2026

View reviewed changes

fix(md,wit): handle remainder of nofmt codeblocks

d184976

mkatychev commented Oct 6, 2026

View reviewed changes

mkatychev mentioned this pull request Oct 7, 2026

fix(markdown,wit,query): handle certain practical edge cases topiary/topiary#1346

Merged

2 of 3 tasks

vados-cosmonic reviewed Oct 7, 2026

View reviewed changes

Navigation Menu

Repository navigation

feat(md,wit): format WIT and nested code inside markdown files - #379

feat(md,wit): format WIT and nested code inside markdown files#379
mkatychev wants to merge 6 commits into
mainfrom
feat/format-markdown-wit

mkatychev commented Oct 6, 2026

Uh oh!

mkatychev Oct 6, 2026

Uh oh!

mkatychev Oct 6, 2026

Uh oh!

mkatychev Oct 6, 2026 •

edited

Loading

Uh oh!

mkatychev Oct 6, 2026 •

edited

Loading

Uh oh!

vados-cosmonic Oct 7, 2026

Uh oh!

mkatychev commented Oct 6, 2026

Uh oh!

mkatychev Oct 6, 2026

Uh oh!

mkatychev commented Oct 6, 2026

Uh oh!

mkatychev Oct 6, 2026 •

edited

Loading

Uh oh!

vados-cosmonic Oct 7, 2026

Uh oh!

mkatychev Oct 7, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mkatychev commented Oct 6, 2026

Uh oh!

mkatychev Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

mkatychev Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

mkatychev Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mkatychev Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vados-cosmonic Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

mkatychev commented Oct 6, 2026

Uh oh!

mkatychev Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

mkatychev commented Oct 6, 2026

Uh oh!

mkatychev Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vados-cosmonic Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

mkatychev Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mkatychev Oct 6, 2026 •

edited

Loading

mkatychev Oct 6, 2026 •

edited

Loading

mkatychev Oct 6, 2026 •

edited

Loading