emdbed/README.md

# emdbed

Embed "things" in your markdown files.

Given the same input, `emdbed` should give idempotent results.

To create an `emdbed` section, use a header and footer as follows
```text
<!-- emdbed: <file> [~<language>] [L<start-line>|/<start-regex>/] [L<end-line>|/<end-regex>/]
<!-- /emdbed -->
```

The regex is [Go flavored](https://golang.org/s/re2syntax), which you can test on [regex101](https://regex101.com/).

## Examples

The following are generated using [readme.go](readme.go) and `go generate ./...`.  
Check the raw markdown for the header selectors used.

An entire file:

<!-- emdbed: emdbed_example_test.go -->
```go
package emdbed

import (
	"fmt"
)

func Example() {
	fi, err := testdata.Open("testdata/main.md")
	defer fi.Close()
	out, err := Convert("testdata", fi)
	if err != nil {
		panic(err)
	}
	fmt.Println(out)
	// Output:
	//<!-- emdbed: main.go -->
	//```go
	//package main
	//
	//import "fmt"
	//
	//func main() {
	//	fmt.Println("Hello, world!")
	//}
	// ```
	//<!-- /emdbed -->
}

```
<!-- /emdbed -->

Just the package:

<!-- emdbed: emdbed_example_test.go L1 L1 -->
```go
package emdbed
```
<!-- /emdbed -->

First line until the end of imports:

<!-- emdbed: emdbed_example_test.go L1 /\)/ -->
```go
package emdbed

import (
	"fmt"
)
```
<!-- /emdbed -->

Only the example func

<!-- emdbed: emdbed_example_test.go /func Example/ /(?m)^\}/ -->
```go
func Example() {
	fi, err := testdata.Open("testdata/main.md")
	defer fi.Close()
	out, err := Convert("testdata", fi)
	if err != nil {
		panic(err)
	}
	fmt.Println(out)
	// Output:
	//<!-- emdbed: main.go -->
	//```go
	//package main
	//
	//import "fmt"
	//
	//func main() {
	//	fmt.Println("Hello, world!")
	//}
	// ```
	//<!-- /emdbed -->
}
```
<!-- /emdbed -->

A file in another directory (choosing/overriding the language)

<!-- emdbed: testdata/main.txt ~go -->
```go
package main

import "fmt"

func main() {
	fmt.Println("This file has no extension")
}
```
<!-- /emdbed -->

## License

[MIT](LICENSE)