Feature request: Allow overriding base header levels for embedded

[shakefu]

Use case:

We have a markdown README like:

# My Project

Blah blah blah blah

## API Documentation

<!-- gomarkdoc:embed -->

... and would like for either the CLI, or preferably the embed comment itself to allow for overriding the .Level of the headers inserted within.

Bonus feature request: Allow for skipping the {{- header .Level .Name -}} and {{- codeBlock "go" .Import -}} sections of the package template since they're a bit redundant in that context.

Proposal

Ideally, some kind of context to the tagging (it gets parsed with a regex, I've seen), e.g.:

<!-- gomarkdown:embed:--no-header,--no-import,--level=3 -->

... with parity in the CLI:

gomarkdoc --verbose --output '{{ .Dir }}/README.md' --embed --embed-no-header --embed-no-import --embed-level=3 ./...

[princjef]

This is an interesting suggestion. The ability to customize the level feels particularly useful for embedding scenarios, especially since the levels are mostly hardcoded right now and would have to be changed in multiple places.

A couple questions:

• Do you need the ability to use different levels for each embed or is a CLI parameter sufficient if it applies the same to all levels?
• Any reason not to simply omit the header and import by customizing the template(s)? I can potentially split the header into its own template like the import is now, but the behavior you're asking for feels more appropriate for the template than as a bespoke parameter. If you want to run embedded and non-embedded scenarios through the same configuration, the tool could provide some sort of isEmbedded function so you can vary the behavior

[shakefu]

• Do you need the ability to use different levels for each embed or is a CLI parameter sufficient if it applies the same to all levels?

My primary use case is embedding in the repo root readme, so really only one level is sufficient. Including the docs in pkg/blah/ readmes would probably warrant multiple levels if they were rendered out simultaneously.

• Any reason not to simply omit the header and import by customizing the template(s)? I can potentially split the header into its own template like the import is now, but the behavior you're asking for feels more appropriate for the template than as a bespoke parameter. If you want to run embedded and non-embedded scenarios through the same configuration, the tool could provide some sort of isEmbedded function so you can vary the behavior

I think I looked at this and decided it wouldn't be trivial, but it's been long enough that I don't recall. Our use case is targeting a pre-commit hook to ensure the docs are always up to date in the codebase across many Go repos, so we were hoping for a standard/cli solution that didn't involve external resources, e.g. a customized template.

[nikolaik]

Super interested in this!

For inspiration there is a similar CLI parameter in the terraform-docs project which also can generate markdown (based on terraform code) and allows embedding into other markdown files. They call it injecting instead of embedding and the parameter is called indent instead of the suggested embed-level.

An example, which adds a reference section in your hand written README:

README.md:

# My module

Some hand written prose

## Reference

<!-- BEGIN_TF_DOCS -->

<!-- END_TF_DOCS -->

Then you can run

$ terraform-docs markdown . --output-file README.md --indent 3