emdbed/README.md

122 lines
2.1 KiB
Markdown
Raw Normal View History

# 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 -->
```
**NOTE:** The above snippet has an extra space at the end in order to keep it from recognizing the footer when generating this README.
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)