Thanks! This is quite comprehensive already and the structure makes sense. I'm about halfway through reviewing.

On writing style, some parts feel sales-pitch-y in a way that I don't think is relevant in developer documentation. There are some inaccuracies that can be adjusted but also some nonsensical statements. (Did you use an LLM to help writing? That's fine, but I'm curious to know if so)

Yeah the docs were generated from my dev notes with claude so the tone is classically LLM'd (sales pitch-y is a nice way to put it). I did a few of slop cleanup but I'll do another to tighten it up this morning.

Alright! In that case I'd also cut down on the length of some of the pages especially around the "recommendations" and "design principles". They're reasonable for the most part, but too generic to add much value IMO.

Gave it another once over and removed some of the overly flowery blocks. It reads as a reasonable first-time-dev resource to me, but please let me know what else you'd like to see changed. Thanks!

Excellent! Thanks for the feedback, pedantry is always welcome when talking docs. Will take another pass at the branch this morning.

Accepted your suggestions, made some more copy edits, and rebased everything together. I only have the one remaining question as to how (if at all) you think we should document the intent of the StrWrite trait.

Thanks! I'm not seeing the rebase yet though, and it looks like the latest commit undoes the changes.

How about something like:

• Custom writer implementations via implementing the StrWrite trait

This is the bit of the crate that I was personally the most interested int and it wasn't clear to me using the existing docs.

That isn't possible right now though. The only public entry points for the HTML module are:

pub fn push_html<'a, I>(s: &mut String, iter: I) {...}
pub fn write_html_fmt<'a, I, W: std::fmt::Write>(writer: W, iter: I) {...}
pub fn write_html_io<'a, I, W: std::io::Write>(writer: W, iter: I) {...}

StrWrite is mainly meant to be an adapter trait. An implementation detail we'd rather not have to expose. If you look at the definition for std::fmt::Write, it is very close to StrWrite:

pub trait Write {
    // Required method
    fn write_str(&mut self, s: &str) -> Result;

    // Provided methods
    fn write_char(&mut self, c: char) -> Result { ... }
    fn write_fmt(&mut self, args: Arguments<'_>) -> Result { ... }
}

So for all intents and purposes, a user of pulldown-cmark should be able to implement fmt::Write for their custom type and use that instead of StrWrite.

The reason we want StrWrite at all is it makes the Error type customizable as an associated type, so we can pass through both std::fmt::Result and std::io::Result without losing anything.

Reading the docs for std::fmt::Error, I notice it mentions that the way IO errors are passed through formatting in the standard library is with an adapter that stores the error:

struct Adapter<'a, T: ?Sized + 'a> {
    inner: &'a mut T,
    error: Result<()>,
}

We could consider something similar for pulldown-cmark in the future as well.

Previous discussions:
#492
#493
#870
#881

TL;DR: StrWrite is an implementation detail to abstract over the fmt and io machinery, since they have different error types. Users can provide custom writers by implementing either fmt::Write or io::Write, whichever is more appropriate.

Unrelated to this PR, that actually cleared up some mystery around the W generic 👍

Indeed, I had to read through those prior discussions again to remind myself of the nuances. Wouldn't hurt to have this distilled in the docs

Actually pushed the rebase now ;)

Thanks for the writing and reviewing work! I will try to review this in the next days.

It looks good to me! I think it can be merged when the last ollpu's comment is fixed. Thanks!

Corrected that reference to be firstpass.rs 👍