Following the formatting guide for go doc links results in the angle brackets being escaped and thus links not being rendered correctly. Is there a way to format links to external resources without just pasting the link? I.E., like this, not like this: https://github.com/rs/zerolog

Example

// GetComponentLogger builds a [ZeroLog] Logger based on provided 'rootLogger' ZeroLog Logger,
// adding 'componentName' and 'levelStr' to log messages.
// Will default to 'Info' Log Level if invalid or no 'levelStr' is provided
//
// [ZeroLog]: https://github.com/rs/zerolog "ZeroLog"
func GetComponentLogger(rootLogger zerolog.Logger, componentName string, levelStr string) zerolog.Logger {
	level, err := zerolog.ParseLevel(levelStr)
	if err != nil {
		level = zerolog.InfoLevel
	}
	return rootLogger.With().Str("component", componentName).Logger().Level(level)
}

Result (raw markdown)

GetComponentLogger builds a \[ZeroLog\] Logger based on provided 'rootLogger' ZeroLog Logger, adding 'componentName' and 'levelStr' to log messages. Will default to 'Info' Log Level if invalid or no 'levelStr' is provided

\[ZeroLog\]: https://github.com/rs/zerolog "ZeroLog"

## func [GetHashicorpComponentLogger](<https://github.com/redacted>)

```go
func GetHashicorpComponentLogger(rootLogger zerolog.Logger, componentName string, levelStr string) *logutils.LevelFilter
\```

Result (as rendered by github)

GetComponentLogger builds a [ZeroLog] Logger based on provided 'rootLogger' ZeroLog Logger, adding 'componentName' and 'levelStr' to log messages. Will default to 'Info' Log Level if invalid or no 'levelStr' is provided

[ZeroLog]: https://github.com/rs/zerolog "ZeroLog"

func GetHashicorpComponentLogger

func GetHashicorpComponentLogger(rootLogger zerolog.Logger, componentName string, levelStr string) *logutils.LevelFilter

I would like to generate documentation for a package in a project, but I only want to output certain functions (based on our internal naming convention). Is there a way to do designate which functions are included in the doc generation? Or must I use a gotxt template for this?

Would it be possible to get examples of how to do this with and without template files, if possible?

I have an example function in my code as follows:

func ExampleClient_Update_unset() {
   ...
}

godoc renders the name as Example (Unset):

gomarkdoc renders the name as Example:

<details><summary>Example</summary>
<p>

Here is the relevant documentation from the testing library:

I'm working on something where I need to use the Markdown generated from gomarkoc, and then use the result in a Docusaurus documentation project.

However, creating a build fails, because the Link is probably wrong, AFAIK, I have seen the syntax to be [text](link) and not [text](<link>).

GitHub Docs Ref: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links

Is there any particular reason for doing this? If not, can we fix this?

Failing use-case: Link

Error:

npm run build

> [email protected] build
> docusaurus build

[INFO] [en] Creating an optimized production build...
Browserslist: caniuse-lite is outdated. Please run:
  npx browserslist@latest --update-db
  Why you should do it regularly: https://github.com/browserslist/browserslist#browsers-data-updating
[info] [webpackbar] Compiling Client
[info] [webpackbar] Compiling Server
Browserslist: caniuse-lite is outdated. Please run:
  npx browserslist@latest --update-db
  Why you should do it regularly: https://github.com/browserslist/browserslist#browsers-data-updating
[success] [webpackbar] Client: Compiled with some errors in 16.3[4](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:5)s


SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/SDK.md: Unexpected token (1[5](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:6)4:0)
  152 | <a name="ExponentialStartStrategy"></a>
Error:  Client bundle compiled with errors therefore further build is impossible.
  153 | ## func [ExponentialStartStrategy](<https://github.com/gojek/courier-go/blob/main/exp_starter.go#L37>)
> 154 | <pre><code parentName="pre" {...{"className":"language-go"}}>{`func ExponentialStartStrategy(ctx context.Context, c interface{ Start() error }, opts ...StartOption)
      | ^
  155 | `}</code></pre>
  15[6](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:7) | <p>{`ExponentialStartStrategy will keep attempting to call Client.Start in the background and retry on error, it will never exit unless the context used to invoke is cancelled. This will NOT stop the client, that is the responsibility of caller.`}</p>
  15[7](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:8) | <a name="Version"></a>
SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/otelcourier.md: Unexpected token (52:0)
  50 | <a name="DisableCallbackTracing"></a>
  51 | ## func [DisableCallbackTracing](<https://github.com/gojek/courier-go/blob/main/otelcourier/options.go#L59>)
> 52 | <pre><code parentName="pre" {...{"className":"language-go"}}>{`func DisableCallbackTracing(opts *traceOptions)
     | ^
  53 | `}</code></pre>
  54 | <p>{`DisableCallbackTracing disables implicit tracing on subscription callbacks.`}</p>
  55 | <a name="DisablePublisherTracing"></a>
SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/xds/backoff.md: Unexpected token (29:0)
  27 | <a name="Exponential"></a>
  2[8](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:9) | ## type [Exponential](<https://github.com/gojek/courier-go/blob/main/xds/backoff/backoff.go#L27-L30>)
> 2[9](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:10) | <p>{`Exponential implements exponential backoff algorithm as defined in `}<a parentName="p" {...{"href":"https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md"}}>{`https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md`}</a>{`.`}</p>
     | ^
  30 | <pre><code parentName="pre" {...{"className":"language-go"}}>{`type Exponential struct {
  31 |     // Config contains all options to configure the backoff algorithm.
  32 |     Config grpcbackoff.Config
SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/xds/bootstrap.md: Unexpected token (31:0)
  29 | <a name="Config"></a>
  30 | ## type [Config](<https://github.com/gojek/courier-go/blob/main/xds/bootstrap/bootstrap.go#L55-L58>)
> 31 | <p>{`Config provides the xDS client with several key bits of information that it requires in its interaction with the management server. The Config is initialized from the bootstrap file.`}</p>
     | ^
  32 | <pre><code parentName="pre" {...{"className":"language-go"}}>{`type Config struct {
  33 |     // XDSServer is the management server to connect to.
  34 |     XDSServer *ServerConfig \`json:"xds_server"\`
SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/xds/log.md: Unexpected token (26:0)
  24 | <a name="Logger"></a>
  25 | ## type [Logger](<https://github.com/gojek/courier-go/blob/main/xds/log/logger.go#L4-L[11](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:12)>)
> 26 | <p>{`Logger is used to log messages of info, error and debug levels`}</p>
     | ^
  27 | <pre><code parentName="pre" {...{"className":"language-go"}}>{`type Logger interface {
  28 |     // Info is used to log info level log messages
  29 |     Info(msg string, keysAndValues ...interface{})
SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/xds/xDS.md: Unexpected token (34:0)
  [32](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:33) | <a name="Client"></a>
  [33](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:34) | ## type [Client](<https://github.com/gojek/courier-go/blob/main/xds/client.go#L69-L80>)
> 34 | <p>{`Client performs the actual ADS RPCs using the ADS v3 API. It creates an ADS stream on which the xdsTarget resources are received.`}</p>
     | ^
  [35](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:36) | <pre><code parentName="pre" {...{"className":"language-go"}}>{`type Client struct {
  [36](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:37) |     // contains filtered or unexported fields
  [37](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:38) | }
Error: Process completed with exit code 1.

If I change the autogenerated README for this repository without changing the underlying doc.go file, no error is reported when running with -c (a.k.a. mage docVerify)

Hello,

I seem to have an oddity between my local environment and a github actions environment. Some context:

• gomarkdoc v0.4.1
• go v1.19.5
• the repository is a private github repository

I'm using github actions to run gomarkdoc, but with debug logging i see the following error:

skipping remote https://github.com/private/go-lib-env because no default branch was found

Strangely enough, on my local machine this does not happen:

DEBUG found default branch main for remote [email protected]/go-lib-env.git dir=./pkg/env

All my other go tools work just fine:

• i use git config --global url."https://username:${GITHUB_TOKEN}@github.com".insteadOf "https://github.com" to configure https access to the git repos
• i also set export GOPRIVATE=github.com/private for access to private repos.

I still can't quite figure out why this doesn't work on the github actions build server.

If the repository does not have a ref to HEAD (ie. it was created locally, not cloned) the remote will go undetected and urls will be missing from the docs.

Temporary fix is to manually add git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/$(default_branch).

Any ideas on a nice way to handle this case inside the gomarkdoc without making any surprising assumptions?

Hello! Very nice tool. I just wanted to request official support for pre-commit if at all possible as this would be a very nice integration if working appropriately.

This team from turo has attempted it:
https://github.com/turo/pre-commit-hooks

The problem is the re-embedding seems to always cause a pre-commit failure and re-indexing of the main README.md, so there's an infinite recursion of failure.

Hi, I use your tool to generate markdown and another tool to convert markdown to asciidoctor. I'm in a multi lang environment where we use asciidoctor for all documentation including code.

Can you give me a little aid to get me started to create that? Or isn't that possible within the current architecture?

Cheers,
Mario :)

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 ./...

Would be nice to annotate markdown's codeblock with a language such that it would have the correct style on github/gitlab/etc..

As an example the auto generated README from this repo would result in a go formatted code block, instead of a generic code block:

• https://github.com/princjef/gomarkdoc#programmatic-usage

The markdown would render as:

package main

import (
	"go/build"
	"fmt"
	"os"

	"github.com/princjef/gomarkdoc"
	"github.com/princjef/gomarkdoc/lang"
	"github.com/princjef/gomarkdoc/logger"
)
...

There is a little formatting issue in the Index link text for functions which have signature in multiple lines.

This function:

func (vc *ViperConfiguration) Abc(
    name xyz.ProviderName,
    output interface{},
) error

has index link text:

func (vc *ViperConfiguration) Abc( name xyz.ProviderName, output interface{}, ) error

but it should be:

func (vc *ViperConfiguration) Abc(name xyz.ProviderName, output interface{}) error

Hi, I was trying out Go 1.18 when I figured that gomarkdoc currently doesn't work with Go 1.18 projects that use generics.

For some code that uses generics

type Set[T comparable] map[T]bool

gomarkdoc currently gives error with 1.18 projects

gomarkdoc: failed to parse package: generic/set.go:4:12: expected ']', found comparable (and 1 more errors)

Wondering if the support is planned after a stable 1.18 release. Not sure how much effort this would be, I'm hoping it'll just require updating some parsing dependency in gomarkdoc.

When using the parameter -output with a template like doc/{{.Dir}}/README.md, the cli returns an error if the folder doesn't exist.

failed to write output file doc\pkg\foo\README.md: open doc\pkg\foo\README.md: The system cannot find the path specified.

Maybe the cli should automatically create the folder or it could be a new flag -create-dirs.

I have already made a fork for it. If it is accepted, I will open a PR:
https://github.com/michaelmass/gomarkdoc/commit/b868c0fc4a6a07512eaf94f072f4325ba6efc709

Assuming a tree-like package organization exists in a project, is there a way to generate documentation for all of them with a root index file?

When try to install the package with

go get -u github.com/princjef/gomarkdoc/cmd/gomarkdoc

The output is

go: found github.com/princjef/gomarkdoc/cmd/gomarkdoc in github.com/princjef/gomarkdoc v0.1.1
go: github.com/magiconair/properties upgrade => v1.8.4
go: github.com/spf13/viper upgrade => v1.7.1
go: golang.org/x/text upgrade => v0.3.3
go: gopkg.in/yaml.v2 upgrade => v2.3.0
go: github.com/spf13/cobra upgrade => v1.0.0
go: github.com/spf13/afero upgrade => v1.4.0
go: github.com/konsorten/go-windows-terminal-sequences upgrade => v1.0.3
go: golang.org/x/crypto upgrade => v0.0.0-20200820211705-5c72a883971a
go: github.com/mitchellh/mapstructure upgrade => v1.3.3
go: golang.org/x/sys upgrade => v0.0.0-20200926100807-9d91bd62050c
go: github.com/mattn/go-colorable upgrade => v0.1.7
go: github.com/fsnotify/fsnotify upgrade => v1.4.9
go: github.com/sirupsen/logrus upgrade => v1.6.0
go: github.com/mattn/go-runewidth upgrade => v0.0.9
go: github.com/mattn/go-isatty upgrade => v0.0.12
go: golang.org/x/net upgrade => v0.0.0-20200925080053-05aa5d4ee321
go: github.com/pelletier/go-toml upgrade => v1.8.1
go: gopkg.in/russross/blackfriday.v2 upgrade => v2.0.1
go: github.com/mgutz/ansi upgrade => v0.0.0-20200706080929-d51e80ef957d
go: github.com/fatih/color upgrade => v1.9.0
go: github.com/spf13/pflag upgrade => v1.0.5
go: github.com/spf13/jwalterweatherman upgrade => v1.1.0
go: github.com/cheggaaa/pb/v3 upgrade => v3.0.5
go: github.com/mitchellh/go-homedir upgrade => v1.1.0
go: github.com/sergi/go-diff upgrade => v1.1.0
go: github.com/spf13/cast upgrade => v1.3.1
go get: gopkg.in/russross/[email protected] updating to
        gopkg.in/russross/[email protected]: parsing go.mod:
        module declares its path as: github.com/russross/blackfriday/v2
                but was required as: gopkg.in/russross/blackfriday.v2

It seems fails installing the package because running

gomarkdoc . > doc.md

outputs gomarkdoc: command not found.

I am using go version go1.14.6.

Since Go 1.17, one can no longer install packages/modules via the go get method as per: https://github.com/princjef/gomarkdoc/blob/master/README.md?L=20

L20: GO111MODULE=on go get -u github.com/princjef/gomarkdoc/cmd/gomarkdoc

Hey there friend 👋

Love the tool. Just noticed that the installation command of go get -u github.com/princejef/gomarkdoc/cmd/gomarkdoc appears to get mad at BlackFriday v2 being missing.

However if I run GO111MODULE=on go get -u github.com/princejef/gomarkdoc/cmd/gomarkdoc, the installation works great and I'm up and running with your tool! Could be a Black Friday issue, but wanted to give heads up.

Tldr; just in case other people run into the same issue, would you be able to update the readme with the GOMODULE-prepended install command?

Hi, I noticed that some characters are not shown properly:

I guess it's the file encoding.

Repository to reproduce: https://github.com/pterm/pterm

When utilizing embedding and file created by gomarkdoc itself, the file will have execution (+x) permissions for user, group and all, i.e.

11:05 $ ls -la
total 36
drwxrwxr-x 2 dvolodin dvolodin 4096 Jul  4 10:34 .
drwxrwxr-x 3 dvolodin dvolodin 4096 Jul  4 10:34 ..
-rw-rw-r-- 1 dvolodin dvolodin 6184 Jul  4 10:34 helm-client.md
-rwxrwxr-x 1 dvolodin dvolodin 3786 Jul  4 10:34 provider-builder.md

generation with:

gomarkdoc ./provider/impl/v1alpha1/ --repository.default-branch $(DEFAULT_BRANCH) -e -o docs/user-guide/provider-builder.md

In preparation for the release of Go 1.18, I have been testing out generics. I noticed that gomarkdoc doesn't always use correct formatting when generic types are involved. See https://github.com/zyedidia/generic/tree/master/avl for an example.

I realize this might be a bit ahead of time, but just wanted to document the issue so it can be resolved before the release of 1.18. Thanks!

We are currently looking for a solution that allows us to document our binaries (description of options/arguments, usage, tutorials, ...) + Go packages + packages of other languages + Rest/... APIs.

I stumbled upon this project and the description seems nice. However, i do not see any linked examples for documentation sites that are generated. Could you please add some?

It would be great if this package could support generating docs that are compatible with Pandoc.

Currently the major issue seems to be the anchor link before the title, as that causes Pandoc to not generate the title properly (prefixing it with ## in the rendered output).

There might be other incompatibilities, but that's the first one I've run into.

Steps to reproduce:

• update docstrings in some repo, do not regenerate documentation with gomarkdoc
• run gomarkdoc with both --check and --embed flags enabled

Expected results:

• gomarkdoc complains in the console about docs not being up to date and returns with non-zero exit code

Actual results:

• gomarkdoc complains in the console about docs not being up to date, but still returns zero exit code

Impact:

• this behaviour makes it impossible to create a CI check of whether documentation is up to date, when embed mode is enabled

URLs included in documentation, e.g.

/*
Package monitoring declares types for Sourcegraph's monitoring generator as well as the generator implementation itself.

To learn more about developing monitoring, see the guide: https://about.sourcegraph.com/handbook/engineering/observability/monitoring

To learn more about the generator, see the top-level program: https://github.com/sourcegraph/sourcegraph/tree/main/monitoring
*/
package monitoring

are escaped when rendered, and not clickable:

I am seeing that when an example function is defined in a _test.go file has some build tag constraint, those constraints don't seem to be respected by gomarkdoc.

I put together a little repo to demonstrate this. One func Example() is defined in a file that should only be selected when the build tag example is on, another func Example() is in a file that should only be selected when the build tag is off. But both examples show up when I run gomarkdoc, regardless of whether I specify any build tags in GOFLAGS or --tags.

gofmt has a new # syntax for inferred headers. see release notes https://go.dev/doc/go1.19#go-doc.

support this by not escaping headers beginning with # in godoc.

example

example.go

// Package example ...
//
// # Documentation
// 
// documentation...
package example

results in markdown with the header's # escaped

README.go

...
\# Documentation
...

When I run gomarkdoc ./... > doc.md on a package whose name is main I was expecting that it would skip creating the import statement or that it would contain a go install statement instead.

Hi! I noticed that when I generate markdown files containing the symbol "," it prints out in the md file this: "'backslash'," (I put the 'backslash' string instead of the symbol because it does not prints the symbol here.

Is there something I'm missing or is it a bug?

To test the issue you can simply create a comment (with one or more lines) like the following:
// Lorem ipsum dolor sit amet, hello world

When I locally generate the markdown it seems to differ from the output that is generated when GitHub actions runs the CLI

internal/plugins/appstore/README.md - (expected) (actual)
19 | 19 |   
20 | 20 |   <a name="App"></a>
21 | 21 |   ## type [App](<
https://github.com/jan-xyz/dotfiles/blob/main/internal/plugins/appstore/plugin.go#L14-L17
>)
Error: output does not match current files. Did you forget to run gomarkdoc?

(The expected here is ## type App)

I run it with
github.com/princjef/gomarkdoc/cmd/gomarkdoc --check --output "{{.Dir}}/README.md" --format github ./internal/... to check it and with go run github.com/princjef/gomarkdoc/cmd/gomarkdoc --output "{{.Dir}}/README.md" --format github ./internal/... to generate the markdown.

The Problem

When generating example documentation, all the example code is present and nicely formatted. However, it lacks the actual output of the Example function. For example, given the following myfoo.go:

package myfoo

import "fmt"

func Hello(s string) string {
	return fmt.Sprintf("Hello %s!", s)
}

and its test file myfoo_test.go:

package myfoo


func ExampleHello() {
	s := Hello("Bob")
	fmt.Println(s)
	// Output: Hello Bob!
}

I get the following for my generated markdown:

...

<details><summary>Example</summary>
<p>

```go
{
	s := Hello("Bob")
	fmt.Println(s)

}
```

</p>
</details>

...

This generated example doesn't include my expected output of Hello Bob!, which could be useful for a reader.

Recommendation

In the generated example details, an additional code block could be added that shows the output. For the above example, we could do something like the following:

<details><summary>Example</summary>
<p>

```go
{
	s := Hello("Bob")
	fmt.Println(s)

}
```

Outputs:

```example
Hello Bob!
```

</p>
</details>

Implementation

It appears that the doc.Example struct already has a field called Output which contains the expected output. I suspect it would be as simple as hooking this up with a new method in gomarkdoc/lang.Example, then modifying the example.gotxt template to accommodate the new method.

Noticed this with the v1.0.0 release today.

It appears links are being parsed into link[link](link) which renders incorrectly, for example from the current README: https://pkg.go.dev[https://pkg.go.dev](<https://pkg.go.dev>). It looks like that change happened with #89.

Thanks for the great tool!

I did not see this issue covered, or a supported way to do this. Please let me know if I missed something.

When running gomarkdoc -o '{{.Dir}}/README.md' ./... from a project's root where go mod vendor has been used, gomarkdoc parses and creates README.md files in all vendored paths as well as expected paths. Since vendor is a standard path for vendored code gomarkdoc should ignore that folder by default.

Alternatively, there should be a way to ignore specific paths when invoking the command.

It would be very convenient if we had access to the strings.HasPrefix and a few other strings. functions in templates.

eg:

type DList
func NewDListT any *DList[T]

See the following link for more examples:

https://github.com/chen3feng/contalgo/blob/decca4ca119775b6bed62a1ef5b35e76696f17f3/README.md#index

Thanks.

I was wondering if we can implemented solution where when when use -e flag with a wildcard we don't append new generated docs to an already generated docs?

As far as I can see, it is not possible to define additional Template functions. For example, the following code defines some functions:

		if renderer.tmpl == nil {
			tmpl := template.New(name)
			tmpl.Funcs(map[string]interface{}{
				"add": func(n1, n2 int) int {
					return n1 + n2
				},
 ...

but it would be great to be able to add others (such as the functions provided by Sprig for instance), when creating a new renderer (NewRenderer).

The # syntax was added in Go 1.19. Before Go 1.19, headings were identified implicitly by single-line paragraphs satisfying certain conditions, most notably the lack of any terminating punctuation.

The current master branch doesn't yet support this change, instead writing a literal '#':

https://go.dev/doc/comment#headings

When i let it run with GOFLAGS="-tags=psql" gomarkdoc ./... and have packages needing this build tag e.g. // +build psql the doc is not generated for such files. GOFLAGS env variable is not honored and i dont see any other way to include such files.

Any Idea ?

I want to generate a relaitive link in the doc to a yaml file that is in the repo istelf.

In md I would do:

see example: [filename.yaml](./path-to-yaml.yml)

but if I do this with the doc I get:

golang:

// see example: [filename.yaml](./path-to-yaml.yml)

output using gomarkdoc --output test.md . --format azure-devops

see example: \[filename.yaml\]\(./path\-to\-yaml.yml\)

I tried several variants of this but nothing I tried works.

thx

Hi, first of all I love this project. I'm super excited to find a godoc style generator that works for private projects.

I integrated the generator into my project for work, but found that outputting to README.md would clobber any existing README data, so the initial solution is to send output to a separate file: gomarkdoc --output '{{.Dir}}/DOCUMENTATION.md' ./....

This works fine, but visibility is lower. I'd love for this tool to detect an existing README.md file, and append documentation to the end, rather than overriding the existing content. Ideally it could detect the comment at the start of the generated documentation, split the file contents, and replace the existing documentation on regeneration.

Hello!

I've just discovered your tool, it's awesome and really useful!

I'm using your tool for a work project, but I need to tweak a bit the rendered markdown files. I saw that there are bunch of markdown helpers (bold, header, link...) in format/base.go that you use in all the implementation of format.Format (PlainMarkdown, GitHubFlavoredMarkdown and AzureDevOpsMarkdown).

I was wondering if it would be possible to export those helpers so that its easy to create a custom implementation of format.Format, without having to rewrite those helpers?

I'd be happy to send a PR if that's okay with you!

There are multiple newlines are generated during templates processing which is known behaviour, i.e.

func (h *Client) IsReleaseInstalled(...) (bool, error)



Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)


<!-- gomarkdoc:embed:end -->

But multiple empty lines for the .md files are interpreting as a single one.
As we can control the output from the template we could probably add following postprocessing at the end of the template or whole *.md file processing

regexp.MustCompile(`[\r\n]{2,}`).ReplaceAllString(result.String(), "\n\n")

Hi, I've noticed that, when generating markdown files with some characters like "*(){}[]-", the output is not correct and backslashes are added to the md file before each of the characters. See example below:

Source comment:

// **param** c (context.Context): Execution context

markdown output

\*\*param\*\* ctx \(context.Context\): Execution context

This issue is similar to issue #68