diff --git a/format/README.md b/format/README.md index 2426ba7..8ba4f22 100755 --- a/format/README.md +++ b/format/README.md @@ -57,7 +57,7 @@ Each of the formats in this package contains the same set of formatting function - [func (f *PlainMarkdown) RawHeader(level int, text string) (string, error)](<#func-plainmarkdown-rawheader>) -## type [AzureDevOpsMarkdown]() +## type [AzureDevOpsMarkdown]() AzureDevOpsMarkdown provides a Format which is compatible with Azure DevOps's syntax and semantics\. See the Azure DevOps documentation for more details about their markdown format: https://docs.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops @@ -65,7 +65,7 @@ AzureDevOpsMarkdown provides a Format which is compatible with Azure DevOps's sy type AzureDevOpsMarkdown struct{} ``` -### func \(\*AzureDevOpsMarkdown\) [Accordion]() +### func \(\*AzureDevOpsMarkdown\) [Accordion]() ```go func (f *AzureDevOpsMarkdown) Accordion(title, body string) (string, error) @@ -73,7 +73,7 @@ func (f *AzureDevOpsMarkdown) Accordion(title, body string) (string, error) Accordion generates a collapsible content\. The accordion's visible title while collapsed is the provided title and the expanded content is the body\. -### func \(\*AzureDevOpsMarkdown\) [AccordionHeader]() +### func \(\*AzureDevOpsMarkdown\) [AccordionHeader]() ```go func (f *AzureDevOpsMarkdown) AccordionHeader(title string) (string, error) @@ -87,7 +87,7 @@ The AccordionHeader is expected to be used in conjunction with AccordionTerminat accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator() ``` -### func \(\*AzureDevOpsMarkdown\) [AccordionTerminator]() +### func \(\*AzureDevOpsMarkdown\) [AccordionTerminator]() ```go func (f *AzureDevOpsMarkdown) AccordionTerminator() (string, error) @@ -95,7 +95,7 @@ func (f *AzureDevOpsMarkdown) AccordionTerminator() (string, error) AccordionTerminator generates the code necessary to terminate an accordion after the body\. It is expected to be used in conjunction with AccordionHeader\(\)\. See AccordionHeader for a full description\. -### func \(\*AzureDevOpsMarkdown\) [Bold]() +### func \(\*AzureDevOpsMarkdown\) [Bold]() ```go func (f *AzureDevOpsMarkdown) Bold(text string) (string, error) @@ -103,7 +103,7 @@ func (f *AzureDevOpsMarkdown) Bold(text string) (string, error) Bold converts the provided text to bold -### func \(\*AzureDevOpsMarkdown\) [CodeBlock]() +### func \(\*AzureDevOpsMarkdown\) [CodeBlock]() ```go func (f *AzureDevOpsMarkdown) CodeBlock(language, code string) (string, error) @@ -111,7 +111,7 @@ func (f *AzureDevOpsMarkdown) CodeBlock(language, code string) (string, error) CodeBlock wraps the provided code as a code block and tags it with the provided language \(or no language if the empty string is provided\)\. -### func \(\*AzureDevOpsMarkdown\) [CodeHref]() +### func \(\*AzureDevOpsMarkdown\) [CodeHref]() ```go func (f *AzureDevOpsMarkdown) CodeHref(loc lang.Location) (string, error) @@ -119,7 +119,7 @@ func (f *AzureDevOpsMarkdown) CodeHref(loc lang.Location) (string, error) CodeHref generates an href to the provided code entry\. -### func \(\*AzureDevOpsMarkdown\) [Escape]() +### func \(\*AzureDevOpsMarkdown\) [Escape]() ```go func (f *AzureDevOpsMarkdown) Escape(text string) string @@ -127,7 +127,7 @@ func (f *AzureDevOpsMarkdown) Escape(text string) string Escape escapes special markdown characters from the provided text\. -### func \(\*AzureDevOpsMarkdown\) [Header]() +### func \(\*AzureDevOpsMarkdown\) [Header]() ```go func (f *AzureDevOpsMarkdown) Header(level int, text string) (string, error) @@ -135,7 +135,7 @@ func (f *AzureDevOpsMarkdown) Header(level int, text string) (string, error) Header converts the provided text into a header of the provided level\. The level is expected to be at least 1\. -### func \(\*AzureDevOpsMarkdown\) [Link]() +### func \(\*AzureDevOpsMarkdown\) [Link]() ```go func (f *AzureDevOpsMarkdown) Link(text, href string) (string, error) @@ -143,7 +143,7 @@ func (f *AzureDevOpsMarkdown) Link(text, href string) (string, error) Link generates a link with the given text and href values\. -### func \(\*AzureDevOpsMarkdown\) [ListEntry]() +### func \(\*AzureDevOpsMarkdown\) [ListEntry]() ```go func (f *AzureDevOpsMarkdown) ListEntry(depth int, text string) (string, error) @@ -151,7 +151,7 @@ func (f *AzureDevOpsMarkdown) ListEntry(depth int, text string) (string, error) ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth\. A depth of 0 is considered the topmost level of list\. -### func \(\*AzureDevOpsMarkdown\) [LocalHref]() +### func \(\*AzureDevOpsMarkdown\) [LocalHref]() ```go func (f *AzureDevOpsMarkdown) LocalHref(headerText string) (string, error) @@ -159,7 +159,7 @@ func (f *AzureDevOpsMarkdown) LocalHref(headerText string) (string, error) LocalHref generates an href for navigating to a header with the given headerText located within the same document as the href itself\. Link generation follows the guidelines here: https://docs.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops#anchor-links -### func \(\*AzureDevOpsMarkdown\) [Paragraph]() +### func \(\*AzureDevOpsMarkdown\) [Paragraph]() ```go func (f *AzureDevOpsMarkdown) Paragraph(text string) (string, error) @@ -167,7 +167,7 @@ func (f *AzureDevOpsMarkdown) Paragraph(text string) (string, error) Paragraph formats a paragraph with the provided text as the contents\. -### func \(\*AzureDevOpsMarkdown\) [RawHeader]() +### func \(\*AzureDevOpsMarkdown\) [RawHeader]() ```go func (f *AzureDevOpsMarkdown) RawHeader(level int, text string) (string, error) @@ -240,7 +240,7 @@ type Format interface { } ``` -## type [GitHubFlavoredMarkdown]() +## type [GitHubFlavoredMarkdown]() GitHubFlavoredMarkdown provides a Format which is compatible with GitHub Flavored Markdown's syntax and semantics\. See GitHub's documentation for more details about their markdown format: https://guides.github.com/features/mastering-markdown/ @@ -248,7 +248,7 @@ GitHubFlavoredMarkdown provides a Format which is compatible with GitHub Flavore type GitHubFlavoredMarkdown struct{} ``` -### func \(\*GitHubFlavoredMarkdown\) [Accordion]() +### func \(\*GitHubFlavoredMarkdown\) [Accordion]() ```go func (f *GitHubFlavoredMarkdown) Accordion(title, body string) (string, error) @@ -256,7 +256,7 @@ func (f *GitHubFlavoredMarkdown) Accordion(title, body string) (string, error) Accordion generates a collapsible content\. The accordion's visible title while collapsed is the provided title and the expanded content is the body\. -### func \(\*GitHubFlavoredMarkdown\) [AccordionHeader]() +### func \(\*GitHubFlavoredMarkdown\) [AccordionHeader]() ```go func (f *GitHubFlavoredMarkdown) AccordionHeader(title string) (string, error) @@ -270,7 +270,7 @@ The AccordionHeader is expected to be used in conjunction with AccordionTerminat accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator() ``` -### func \(\*GitHubFlavoredMarkdown\) [AccordionTerminator]() +### func \(\*GitHubFlavoredMarkdown\) [AccordionTerminator]() ```go func (f *GitHubFlavoredMarkdown) AccordionTerminator() (string, error) @@ -278,7 +278,7 @@ func (f *GitHubFlavoredMarkdown) AccordionTerminator() (string, error) AccordionTerminator generates the code necessary to terminate an accordion after the body\. It is expected to be used in conjunction with AccordionHeader\(\)\. See AccordionHeader for a full description\. -### func \(\*GitHubFlavoredMarkdown\) [Bold]() +### func \(\*GitHubFlavoredMarkdown\) [Bold]() ```go func (f *GitHubFlavoredMarkdown) Bold(text string) (string, error) @@ -286,7 +286,7 @@ func (f *GitHubFlavoredMarkdown) Bold(text string) (string, error) Bold converts the provided text to bold -### func \(\*GitHubFlavoredMarkdown\) [CodeBlock]() +### func \(\*GitHubFlavoredMarkdown\) [CodeBlock]() ```go func (f *GitHubFlavoredMarkdown) CodeBlock(language, code string) (string, error) @@ -294,7 +294,7 @@ func (f *GitHubFlavoredMarkdown) CodeBlock(language, code string) (string, error CodeBlock wraps the provided code as a code block and tags it with the provided language \(or no language if the empty string is provided\)\. -### func \(\*GitHubFlavoredMarkdown\) [CodeHref]() +### func \(\*GitHubFlavoredMarkdown\) [CodeHref]() ```go func (f *GitHubFlavoredMarkdown) CodeHref(loc lang.Location) (string, error) @@ -302,7 +302,7 @@ func (f *GitHubFlavoredMarkdown) CodeHref(loc lang.Location) (string, error) CodeHref generates an href to the provided code entry\. -### func \(\*GitHubFlavoredMarkdown\) [Escape]() +### func \(\*GitHubFlavoredMarkdown\) [Escape]() ```go func (f *GitHubFlavoredMarkdown) Escape(text string) string @@ -310,7 +310,7 @@ func (f *GitHubFlavoredMarkdown) Escape(text string) string Escape escapes special markdown characters from the provided text\. -### func \(\*GitHubFlavoredMarkdown\) [Header]() +### func \(\*GitHubFlavoredMarkdown\) [Header]() ```go func (f *GitHubFlavoredMarkdown) Header(level int, text string) (string, error) @@ -318,7 +318,7 @@ func (f *GitHubFlavoredMarkdown) Header(level int, text string) (string, error) Header converts the provided text into a header of the provided level\. The level is expected to be at least 1\. -### func \(\*GitHubFlavoredMarkdown\) [Link]() +### func \(\*GitHubFlavoredMarkdown\) [Link]() ```go func (f *GitHubFlavoredMarkdown) Link(text, href string) (string, error) @@ -326,7 +326,7 @@ func (f *GitHubFlavoredMarkdown) Link(text, href string) (string, error) Link generates a link with the given text and href values\. -### func \(\*GitHubFlavoredMarkdown\) [ListEntry]() +### func \(\*GitHubFlavoredMarkdown\) [ListEntry]() ```go func (f *GitHubFlavoredMarkdown) ListEntry(depth int, text string) (string, error) @@ -334,7 +334,7 @@ func (f *GitHubFlavoredMarkdown) ListEntry(depth int, text string) (string, erro ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth\. A depth of 0 is considered the topmost level of list\. -### func \(\*GitHubFlavoredMarkdown\) [LocalHref]() +### func \(\*GitHubFlavoredMarkdown\) [LocalHref]() ```go func (f *GitHubFlavoredMarkdown) LocalHref(headerText string) (string, error) @@ -342,7 +342,7 @@ func (f *GitHubFlavoredMarkdown) LocalHref(headerText string) (string, error) LocalHref generates an href for navigating to a header with the given headerText located within the same document as the href itself\. -### func \(\*GitHubFlavoredMarkdown\) [Paragraph]() +### func \(\*GitHubFlavoredMarkdown\) [Paragraph]() ```go func (f *GitHubFlavoredMarkdown) Paragraph(text string) (string, error) @@ -350,7 +350,7 @@ func (f *GitHubFlavoredMarkdown) Paragraph(text string) (string, error) Paragraph formats a paragraph with the provided text as the contents\. -### func \(\*GitHubFlavoredMarkdown\) [RawHeader]() +### func \(\*GitHubFlavoredMarkdown\) [RawHeader]() ```go func (f *GitHubFlavoredMarkdown) RawHeader(level int, text string) (string, error) @@ -358,7 +358,7 @@ func (f *GitHubFlavoredMarkdown) RawHeader(level int, text string) (string, erro RawHeader converts the provided text into a header of the provided level without escaping the header text\. The level is expected to be at least 1\. -## type [PlainMarkdown]() +## type [PlainMarkdown]() PlainMarkdown provides a Format which is compatible with the base Markdown format specification\. @@ -366,7 +366,7 @@ PlainMarkdown provides a Format which is compatible with the base Markdown forma type PlainMarkdown struct{} ``` -### func \(\*PlainMarkdown\) [Accordion]() +### func \(\*PlainMarkdown\) [Accordion]() ```go func (f *PlainMarkdown) Accordion(title, body string) (string, error) @@ -374,7 +374,7 @@ func (f *PlainMarkdown) Accordion(title, body string) (string, error) Accordion generates a collapsible content\. Since accordions are not supported by plain markdown\, this generates a level 6 header followed by a paragraph\. -### func \(\*PlainMarkdown\) [AccordionHeader]() +### func \(\*PlainMarkdown\) [AccordionHeader]() ```go func (f *PlainMarkdown) AccordionHeader(title string) (string, error) @@ -388,7 +388,7 @@ The AccordionHeader is expected to be used in conjunction with AccordionTerminat accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator() ``` -### func \(\*PlainMarkdown\) [AccordionTerminator]() +### func \(\*PlainMarkdown\) [AccordionTerminator]() ```go func (f *PlainMarkdown) AccordionTerminator() (string, error) @@ -396,7 +396,7 @@ func (f *PlainMarkdown) AccordionTerminator() (string, error) AccordionTerminator generates the code necessary to terminate an accordion after the body\. Since accordions are not supported in plain markdown\, this completes a paragraph section\. It is expected to be used in conjunction with AccordionHeader\(\)\. See AccordionHeader for a full description\. -### func \(\*PlainMarkdown\) [Bold]() +### func \(\*PlainMarkdown\) [Bold]() ```go func (f *PlainMarkdown) Bold(text string) (string, error) @@ -404,7 +404,7 @@ func (f *PlainMarkdown) Bold(text string) (string, error) Bold converts the provided text to bold -### func \(\*PlainMarkdown\) [CodeBlock]() +### func \(\*PlainMarkdown\) [CodeBlock]() ```go func (f *PlainMarkdown) CodeBlock(language, code string) (string, error) @@ -412,7 +412,7 @@ func (f *PlainMarkdown) CodeBlock(language, code string) (string, error) CodeBlock wraps the provided code as a code block\. The provided language is ignored as it is not supported in plain markdown\. -### func \(\*PlainMarkdown\) [CodeHref]() +### func \(\*PlainMarkdown\) [CodeHref]() ```go func (f *PlainMarkdown) CodeHref(loc lang.Location) (string, error) @@ -420,7 +420,7 @@ func (f *PlainMarkdown) CodeHref(loc lang.Location) (string, error) CodeHref always returns the empty string\, as there is no defined file linking format in standard markdown\. -### func \(\*PlainMarkdown\) [Escape]() +### func \(\*PlainMarkdown\) [Escape]() ```go func (f *PlainMarkdown) Escape(text string) string @@ -428,7 +428,7 @@ func (f *PlainMarkdown) Escape(text string) string Escape escapes special markdown characters from the provided text\. -### func \(\*PlainMarkdown\) [Header]() +### func \(\*PlainMarkdown\) [Header]() ```go func (f *PlainMarkdown) Header(level int, text string) (string, error) @@ -436,7 +436,7 @@ func (f *PlainMarkdown) Header(level int, text string) (string, error) Header converts the provided text into a header of the provided level\. The level is expected to be at least 1\. -### func \(\*PlainMarkdown\) [Link]() +### func \(\*PlainMarkdown\) [Link]() ```go func (f *PlainMarkdown) Link(text, href string) (string, error) @@ -444,7 +444,7 @@ func (f *PlainMarkdown) Link(text, href string) (string, error) Link generates a link with the given text and href values\. -### func \(\*PlainMarkdown\) [ListEntry]() +### func \(\*PlainMarkdown\) [ListEntry]() ```go func (f *PlainMarkdown) ListEntry(depth int, text string) (string, error) @@ -452,7 +452,7 @@ func (f *PlainMarkdown) ListEntry(depth int, text string) (string, error) ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth\. A depth of 0 is considered the topmost level of list\. -### func \(\*PlainMarkdown\) [LocalHref]() +### func \(\*PlainMarkdown\) [LocalHref]() ```go func (f *PlainMarkdown) LocalHref(headerText string) (string, error) @@ -460,7 +460,7 @@ func (f *PlainMarkdown) LocalHref(headerText string) (string, error) LocalHref always returns the empty string\, as header links are not supported in plain markdown\. -### func \(\*PlainMarkdown\) [Paragraph]() +### func \(\*PlainMarkdown\) [Paragraph]() ```go func (f *PlainMarkdown) Paragraph(text string) (string, error) @@ -468,7 +468,7 @@ func (f *PlainMarkdown) Paragraph(text string) (string, error) Paragraph formats a paragraph with the provided text as the contents\. -### func \(\*PlainMarkdown\) [RawHeader]() +### func \(\*PlainMarkdown\) [RawHeader]() ```go func (f *PlainMarkdown) RawHeader(level int, text string) (string, error) diff --git a/format/devops.go b/format/devops.go index b34b1f3..38d2bf7 100644 --- a/format/devops.go +++ b/format/devops.go @@ -7,6 +7,7 @@ import ( "regexp" "strings" + "github.com/princjef/gomarkdoc/format/formatcore" "github.com/princjef/gomarkdoc/lang" ) @@ -18,25 +19,25 @@ type AzureDevOpsMarkdown struct{} // Bold converts the provided text to bold func (f *AzureDevOpsMarkdown) Bold(text string) (string, error) { - return bold(text), nil + return formatcore.Bold(text), nil } // CodeBlock wraps the provided code as a code block and tags it with the // provided language (or no language if the empty string is provided). func (f *AzureDevOpsMarkdown) CodeBlock(language, code string) (string, error) { - return gfmCodeBlock(language, code), nil + return formatcore.GFMCodeBlock(language, code), nil } // Header converts the provided text into a header of the provided level. The // level is expected to be at least 1. func (f *AzureDevOpsMarkdown) Header(level int, text string) (string, error) { - return header(level, escape(text)) + return formatcore.Header(level, formatcore.Escape(text)) } // RawHeader converts the provided text into a header of the provided level // without escaping the header text. The level is expected to be at least 1. func (f *AzureDevOpsMarkdown) RawHeader(level int, text string) (string, error) { - return header(level, text) + return formatcore.Header(level, text) } var devOpsWhitespaceRegex = regexp.MustCompile(`\s`) @@ -96,20 +97,20 @@ func (f *AzureDevOpsMarkdown) CodeHref(loc lang.Location) (string, error) { // Link generates a link with the given text and href values. func (f *AzureDevOpsMarkdown) Link(text, href string) (string, error) { - return link(text, href), nil + return formatcore.Link(text, href), nil } // ListEntry generates an unordered list entry with the provided text at the // provided zero-indexed depth. A depth of 0 is considered the topmost level of // list. func (f *AzureDevOpsMarkdown) ListEntry(depth int, text string) (string, error) { - return listEntry(depth, text), nil + return formatcore.ListEntry(depth, text), nil } // Accordion generates a collapsible content. The accordion's visible title // while collapsed is the provided title and the expanded content is the body. func (f *AzureDevOpsMarkdown) Accordion(title, body string) (string, error) { - return gfmAccordion(title, body), nil + return formatcore.GFMAccordion(title, body), nil } // AccordionHeader generates the header visible when an accordion is collapsed. @@ -120,22 +121,22 @@ func (f *AzureDevOpsMarkdown) Accordion(title, body string) (string, error) { // // accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator() func (f *AzureDevOpsMarkdown) AccordionHeader(title string) (string, error) { - return gfmAccordionHeader(title), nil + return formatcore.GFMAccordionHeader(title), nil } // AccordionTerminator generates the code necessary to terminate an accordion // after the body. It is expected to be used in conjunction with // AccordionHeader(). See AccordionHeader for a full description. func (f *AzureDevOpsMarkdown) AccordionTerminator() (string, error) { - return gfmAccordionTerminator(), nil + return formatcore.GFMAccordionTerminator(), nil } // Paragraph formats a paragraph with the provided text as the contents. func (f *AzureDevOpsMarkdown) Paragraph(text string) (string, error) { - return paragraph(text), nil + return formatcore.Paragraph(text), nil } // Escape escapes special markdown characters from the provided text. func (f *AzureDevOpsMarkdown) Escape(text string) string { - return escape(text) + return formatcore.Escape(text) } diff --git a/format/formatcore/README.md b/format/formatcore/README.md new file mode 100755 index 0000000..9d07ba4 --- /dev/null +++ b/format/formatcore/README.md @@ -0,0 +1,129 @@ + + +# formatcore + +```go +import "github.com/princjef/gomarkdoc/format/formatcore" +``` + +## Index + +- [func Bold(text string) string](<#func-bold>) +- [func CodeBlock(code string) string](<#func-codeblock>) +- [func Escape(text string) string](<#func-escape>) +- [func GFMAccordion(title, body string) string](<#func-gfmaccordion>) +- [func GFMAccordionHeader(title string) string](<#func-gfmaccordionheader>) +- [func GFMAccordionTerminator() string](<#func-gfmaccordionterminator>) +- [func GFMCodeBlock(language, code string) string](<#func-gfmcodeblock>) +- [func Header(level int, text string) (string, error)](<#func-header>) +- [func Link(text, href string) string](<#func-link>) +- [func ListEntry(depth int, text string) string](<#func-listentry>) +- [func Paragraph(text string) string](<#func-paragraph>) +- [func PlainText(text string) string](<#func-plaintext>) + + +## func [Bold]() + +```go +func Bold(text string) string +``` + +Bold converts the provided text to bold + +## func [CodeBlock]() + +```go +func CodeBlock(code string) string +``` + +CodeBlock wraps the provided code as a code block\. Language syntax highlighting is not supported\. + +## func [Escape]() + +```go +func Escape(text string) string +``` + +Escape escapes the special characters in the provided text\, but leaves URLs found intact\. Note that the URLs included must begin with a scheme to skip the escaping\. + +## func [GFMAccordion]() + +```go +func GFMAccordion(title, body string) string +``` + +GFMAccordion generates a collapsible content\. The accordion's visible title while collapsed is the provided title and the expanded content is the body\. + +## func [GFMAccordionHeader]() + +```go +func GFMAccordionHeader(title string) string +``` + +GFMAccordionHeader generates the header visible when an accordion is collapsed\. + +The GFMAccordionHeader is expected to be used in conjunction with GFMAccordionTerminator\(\) when the demands of the body's rendering requires it to be generated independently\. The result looks conceptually like the following: + +``` +accordion := GFMAccordionHeader("Accordion Title") + "Accordion Body" + GFMAccordionTerminator() +``` + +## func [GFMAccordionTerminator]() + +```go +func GFMAccordionTerminator() string +``` + +GFMAccordionTerminator generates the code necessary to terminate an accordion after the body\. It is expected to be used in conjunction with GFMAccordionHeader\(\)\. See GFMAccordionHeader for a full description\. + +## func [GFMCodeBlock]() + +```go +func GFMCodeBlock(language, code string) string +``` + +GFMCodeBlock wraps the provided code as a code block and tags it with the provided language \(or no language if the empty string is provided\)\, using the triple backtick format from GitHub Flavored Markdown\. + +## func [Header]() + +```go +func Header(level int, text string) (string, error) +``` + +Header converts the provided text into a header of the provided level\. The level is expected to be at least 1\. + +## func [Link]() + +```go +func Link(text, href string) string +``` + +Link generates a link with the given text and href values\. + +## func [ListEntry]() + +```go +func ListEntry(depth int, text string) string +``` + +ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth\. A depth of 0 is considered the topmost level of list\. + +## func [Paragraph]() + +```go +func Paragraph(text string) string +``` + +Paragraph formats a paragraph with the provided text as the contents\. + +## func [PlainText]() + +```go +func PlainText(text string) string +``` + +PlainText converts a markdown string to the plain text that appears in the rendered output\. + + + +Generated by [gomarkdoc]() diff --git a/format/base.go b/format/formatcore/base.go similarity index 68% rename from format/base.go rename to format/formatcore/base.go index 994ce61..522349c 100644 --- a/format/base.go +++ b/format/formatcore/base.go @@ -1,4 +1,4 @@ -package format +package formatcore import ( "errors" @@ -10,18 +10,18 @@ import ( "mvdan.cc/xurls/v2" ) -// bold converts the provided text to bold -func bold(text string) string { +// Bold converts the provided text to bold +func Bold(text string) string { if text == "" { return "" } - return fmt.Sprintf("**%s**", escape(text)) + return fmt.Sprintf("**%s**", Escape(text)) } -// codeBlock wraps the provided code as a code block. Language syntax +// CodeBlock wraps the provided code as a code block. Language syntax // highlighting is not supported. -func codeBlock(code string) string { +func CodeBlock(code string) string { var builder strings.Builder lines := strings.Split(code, "\n") @@ -33,16 +33,16 @@ func codeBlock(code string) string { return builder.String() } -// gfmCodeBlock wraps the provided code as a code block and tags it with the +// GFMCodeBlock wraps the provided code as a code block and tags it with the // provided language (or no language if the empty string is provided), using // the triple backtick format from GitHub Flavored Markdown. -func gfmCodeBlock(language, code string) string { +func GFMCodeBlock(language, code string) string { return fmt.Sprintf("```%s\n%s\n```\n\n", language, strings.TrimSpace(code)) } -// header converts the provided text into a header of the provided level. The +// Header converts the provided text into a header of the provided level. The // level is expected to be at least 1. -func header(level int, text string) (string, error) { +func Header(level int, text string) (string, error) { if level < 1 { return "", errors.New("format: header level cannot be less than 1") } @@ -64,8 +64,8 @@ func header(level int, text string) (string, error) { } } -// link generates a link with the given text and href values. -func link(text, href string) string { +// Link generates a link with the given text and href values. +func Link(text, href string) string { if text == "" { return "" } @@ -77,10 +77,10 @@ func link(text, href string) string { return fmt.Sprintf("[%s](<%s>)", text, href) } -// listEntry generates an unordered list entry with the provided text at the +// ListEntry generates an unordered list entry with the provided text at the // provided zero-indexed depth. A depth of 0 is considered the topmost level of // list. -func listEntry(depth int, text string) string { +func ListEntry(depth int, text string) string { // TODO: this is a weird special case if text == "" { return "" @@ -90,35 +90,35 @@ func listEntry(depth int, text string) string { return fmt.Sprintf("%s- %s\n", prefix, text) } -// gfmAccordion generates a collapsible content. The accordion's visible title +// GFMAccordion generates a collapsible content. The accordion's visible title // while collapsed is the provided title and the expanded content is the body. -func gfmAccordion(title, body string) string { - return fmt.Sprintf("
%s\n

\n\n%s

\n
\n\n", title, escape(body)) +func GFMAccordion(title, body string) string { + return fmt.Sprintf("
%s\n

\n\n%s

\n
\n\n", title, Escape(body)) } -// gfmAccordionHeader generates the header visible when an accordion is +// GFMAccordionHeader generates the header visible when an accordion is // collapsed. // -// The gfmAccordionHeader is expected to be used in conjunction with -// gfmAccordionTerminator() when the demands of the body's rendering requires +// The GFMAccordionHeader is expected to be used in conjunction with +// GFMAccordionTerminator() when the demands of the body's rendering requires // it to be generated independently. The result looks conceptually like the // following: // -// accordion := gfmAccordionHeader("Accordion Title") + "Accordion Body" + gfmAccordionTerminator() -func gfmAccordionHeader(title string) string { +// accordion := GFMAccordionHeader("Accordion Title") + "Accordion Body" + GFMAccordionTerminator() +func GFMAccordionHeader(title string) string { return fmt.Sprintf("
%s\n

\n\n", title) } -// gfmAccordionTerminator generates the code necessary to terminate an +// GFMAccordionTerminator generates the code necessary to terminate an // accordion after the body. It is expected to be used in conjunction with -// gfmAccordionHeader(). See gfmAccordionHeader for a full description. -func gfmAccordionTerminator() string { +// GFMAccordionHeader(). See GFMAccordionHeader for a full description. +func GFMAccordionTerminator() string { return "

\n
\n\n" } -// paragraph formats a paragraph with the provided text as the contents. -func paragraph(text string) string { - return fmt.Sprintf("%s\n\n", escape(text)) +// Paragraph formats a paragraph with the provided text as the contents. +func Paragraph(text string) string { + return fmt.Sprintf("%s\n\n", Escape(text)) } var ( @@ -126,7 +126,10 @@ var ( urlRegex = xurls.Strict() // Require a scheme in URLs ) -func escape(text string) string { +// Escape escapes the special characters in the provided text, but leaves URLs +// found intact. Note that the URLs included must begin with a scheme to skip +// the escaping. +func Escape(text string) string { b := []byte(text) var ( @@ -161,9 +164,9 @@ func escapeRaw(segment []byte) []byte { return specialCharacterRegex.ReplaceAll(segment, []byte("\\$1")) } -// plainText converts a markdown string to the plain text that appears in the +// PlainText converts a markdown string to the plain text that appears in the // rendered output. -func plainText(text string) string { +func PlainText(text string) string { md := blackfriday.New(blackfriday.WithExtensions(blackfriday.CommonExtensions)) node := md.Parse([]byte(text)) diff --git a/format/base_test.go b/format/formatcore/base_test.go similarity index 92% rename from format/base_test.go rename to format/formatcore/base_test.go index 0ccf9b8..97a17ab 100644 --- a/format/base_test.go +++ b/format/formatcore/base_test.go @@ -1,4 +1,4 @@ -package format +package formatcore import ( "testing" @@ -51,7 +51,7 @@ func TestPlainText(t *testing.T) { for _, test := range tests { t.Run(test.in, func(t *testing.T) { is := is.New(t) - is.Equal(plainText(test.in), test.out) // Wrong output for plainText() + is.Equal(PlainText(test.in), test.out) // Wrong output for plainText() }) } } @@ -95,7 +95,7 @@ func TestEscape(t *testing.T) { for _, test := range tests { t.Run(test.in, func(t *testing.T) { is := is.New(t) - is.Equal(escape(test.in), test.out) // Wrong output for escape() + is.Equal(Escape(test.in), test.out) // Wrong output for escape() }) } } diff --git a/format/github.go b/format/github.go index a016d0f..b5b5af7 100644 --- a/format/github.go +++ b/format/github.go @@ -6,6 +6,7 @@ import ( "regexp" "strings" + "github.com/princjef/gomarkdoc/format/formatcore" "github.com/princjef/gomarkdoc/lang" ) @@ -17,25 +18,25 @@ type GitHubFlavoredMarkdown struct{} // Bold converts the provided text to bold func (f *GitHubFlavoredMarkdown) Bold(text string) (string, error) { - return bold(text), nil + return formatcore.Bold(text), nil } // CodeBlock wraps the provided code as a code block and tags it with the // provided language (or no language if the empty string is provided). func (f *GitHubFlavoredMarkdown) CodeBlock(language, code string) (string, error) { - return gfmCodeBlock(language, code), nil + return formatcore.GFMCodeBlock(language, code), nil } // Header converts the provided text into a header of the provided level. The // level is expected to be at least 1. func (f *GitHubFlavoredMarkdown) Header(level int, text string) (string, error) { - return header(level, escape(text)) + return formatcore.Header(level, formatcore.Escape(text)) } // RawHeader converts the provided text into a header of the provided level // without escaping the header text. The level is expected to be at least 1. func (f *GitHubFlavoredMarkdown) RawHeader(level int, text string) (string, error) { - return header(level, text) + return formatcore.Header(level, text) } var ( @@ -46,7 +47,7 @@ var ( // LocalHref generates an href for navigating to a header with the given // headerText located within the same document as the href itself. func (f *GitHubFlavoredMarkdown) LocalHref(headerText string) (string, error) { - result := plainText(headerText) + result := formatcore.PlainText(headerText) result = strings.ToLower(result) result = strings.TrimSpace(result) result = gfmWhitespaceRegex.ReplaceAllString(result, "-") @@ -57,7 +58,7 @@ func (f *GitHubFlavoredMarkdown) LocalHref(headerText string) (string, error) { // Link generates a link with the given text and href values. func (f *GitHubFlavoredMarkdown) Link(text, href string) (string, error) { - return link(text, href), nil + return formatcore.Link(text, href), nil } // CodeHref generates an href to the provided code entry. @@ -106,13 +107,13 @@ func (f *GitHubFlavoredMarkdown) CodeHref(loc lang.Location) (string, error) { // provided zero-indexed depth. A depth of 0 is considered the topmost level of // list. func (f *GitHubFlavoredMarkdown) ListEntry(depth int, text string) (string, error) { - return listEntry(depth, text), nil + return formatcore.ListEntry(depth, text), nil } // Accordion generates a collapsible content. The accordion's visible title // while collapsed is the provided title and the expanded content is the body. func (f *GitHubFlavoredMarkdown) Accordion(title, body string) (string, error) { - return gfmAccordion(title, body), nil + return formatcore.GFMAccordion(title, body), nil } // AccordionHeader generates the header visible when an accordion is collapsed. @@ -123,22 +124,22 @@ func (f *GitHubFlavoredMarkdown) Accordion(title, body string) (string, error) { // // accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator() func (f *GitHubFlavoredMarkdown) AccordionHeader(title string) (string, error) { - return gfmAccordionHeader(title), nil + return formatcore.GFMAccordionHeader(title), nil } // AccordionTerminator generates the code necessary to terminate an accordion // after the body. It is expected to be used in conjunction with // AccordionHeader(). See AccordionHeader for a full description. func (f *GitHubFlavoredMarkdown) AccordionTerminator() (string, error) { - return gfmAccordionTerminator(), nil + return formatcore.GFMAccordionTerminator(), nil } // Paragraph formats a paragraph with the provided text as the contents. func (f *GitHubFlavoredMarkdown) Paragraph(text string) (string, error) { - return paragraph(text), nil + return formatcore.Paragraph(text), nil } // Escape escapes special markdown characters from the provided text. func (f *GitHubFlavoredMarkdown) Escape(text string) string { - return escape(text) + return formatcore.Escape(text) } diff --git a/format/plain.go b/format/plain.go index 487df5c..c886317 100644 --- a/format/plain.go +++ b/format/plain.go @@ -3,6 +3,7 @@ package format import ( "fmt" + "github.com/princjef/gomarkdoc/format/formatcore" "github.com/princjef/gomarkdoc/lang" ) @@ -12,25 +13,25 @@ type PlainMarkdown struct{} // Bold converts the provided text to bold func (f *PlainMarkdown) Bold(text string) (string, error) { - return bold(text), nil + return formatcore.Bold(text), nil } // CodeBlock wraps the provided code as a code block. The provided language is // ignored as it is not supported in plain markdown. func (f *PlainMarkdown) CodeBlock(language, code string) (string, error) { - return codeBlock(code), nil + return formatcore.CodeBlock(code), nil } // Header converts the provided text into a header of the provided level. The // level is expected to be at least 1. func (f *PlainMarkdown) Header(level int, text string) (string, error) { - return header(level, escape(text)) + return formatcore.Header(level, formatcore.Escape(text)) } // RawHeader converts the provided text into a header of the provided level // without escaping the header text. The level is expected to be at least 1. func (f *PlainMarkdown) RawHeader(level int, text string) (string, error) { - return header(level, text) + return formatcore.Header(level, text) } // LocalHref always returns the empty string, as header links are not supported @@ -47,25 +48,25 @@ func (f *PlainMarkdown) CodeHref(loc lang.Location) (string, error) { // Link generates a link with the given text and href values. func (f *PlainMarkdown) Link(text, href string) (string, error) { - return link(text, href), nil + return formatcore.Link(text, href), nil } // ListEntry generates an unordered list entry with the provided text at the // provided zero-indexed depth. A depth of 0 is considered the topmost level of // list. func (f *PlainMarkdown) ListEntry(depth int, text string) (string, error) { - return listEntry(depth, text), nil + return formatcore.ListEntry(depth, text), nil } // Accordion generates a collapsible content. Since accordions are not supported // by plain markdown, this generates a level 6 header followed by a paragraph. func (f *PlainMarkdown) Accordion(title, body string) (string, error) { - h, err := header(6, title) + h, err := formatcore.Header(6, title) if err != nil { return "", err } - return fmt.Sprintf("%s%s", h, paragraph(body)), nil + return fmt.Sprintf("%s%s", h, formatcore.Paragraph(body)), nil } // AccordionHeader generates the header visible when an accordion is collapsed. @@ -78,7 +79,7 @@ func (f *PlainMarkdown) Accordion(title, body string) (string, error) { // // accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator() func (f *PlainMarkdown) AccordionHeader(title string) (string, error) { - return header(6, title) + return formatcore.Header(6, title) } // AccordionTerminator generates the code necessary to terminate an accordion @@ -91,10 +92,10 @@ func (f *PlainMarkdown) AccordionTerminator() (string, error) { // Paragraph formats a paragraph with the provided text as the contents. func (f *PlainMarkdown) Paragraph(text string) (string, error) { - return paragraph(text), nil + return formatcore.Paragraph(text), nil } // Escape escapes special markdown characters from the provided text. func (f *PlainMarkdown) Escape(text string) string { - return escape(text) + return formatcore.Escape(text) }