This seems reasonable to me, and the API surface is small.

But the name Op is poor. I'd prefer BlockType (or maybe BlockKind), so the new API might look like this:

func Blocks(text string) []Block

type Block struct {
        Type BlockType
        Lines []string
}

type BlockType int

const (
        Paragraph BlockType = iota
        Heading
        Preformatted
)

Thoughts from @griesemer, @bradfitz? Anyone else?

As the author of this code, I think it is a mistake to expand the API here. That hard-codes some of today's choices in ways that are left much more malleable by the current ToText/ToHTML API.

Thanks @rsc ; what would you suggest be done then to allow others to write code that generates other formats? The choice most people seem to reach for is to simply duplicate what's there since it can't be reused directly, which seems unfortunate. Is there a better alternative?

Duplicating what's there is preferable to committing to an API that we may regret. There are just not that many formats, and copy+modify is a perfectly acceptable strategy.

@rsc if exporting the interfaces is undesirable, would there be any objection to renaming the existing ones (maintaining lowercase so as to not expose them) per @adg 's suggestion? Or is that sort of change generally frowned upon. I only ask because at least then, when it's copied somewhere else, it would likely have more suitable naming and thus be easier to find later.

The API is indeed far from perfect, though I'd completely be okay if it were just exposed as is, as one who has just copied it into my own packages in the past.

Here's a rough sketch of an alternative API, that would make most tasks simpler and be a bit more idiomatic.

The names are largely immaterial, and almost certainly the first thing I thought of; the functionality and structure is what I'm suggesting.

type Node interface { //or Block or whatever
   //for headers Text() == Lines()[0]
   //for paragraphs Text() == strings.Join(Lines(), " ") 
   //    where each line in Lines() has been run through strings.TrimSpace
   //for preformatted Text() == strings.Join(Lines(), "\n"),
   //    where no line in Lines() contains the initial indent that marked this node as preformatted
   Text() string
   Lines() []string //each line in the node with type-specific processing as described above
   Original() string //the slice of the original text string with no parsing
}

type NodeHeader struct {...} //all these implement Node, none export anything

type NodePreformatted struct {...}

type NodeParagraph struct {...}

func Parse(text string) []Node

Type switching would replace op.

Lines() would be equivalent to the lines field on block.

Note that

func OriginalInvariant(text string) bool {
  s := ""
  for _, n := range Parse(text) {
    s += n.Original()
  }
  return s == text
}

would return true for all text, allowing line numbering and the like to be derived if necessary.

The Text() method (named like the method on bufio.Scanner for the same reason) would cover the majority of uses and Lines() and Original() would allow any others.

I didn't include a node() method in the interface because it doesn't matter. If someone wants to define their own Node and reparse certain nodes using Original, I say let them go nuts.

Based on @rsc 's comments, I'm closing my request. I will attempt to address this in a different manner.