Literate

module Literate


Assembly	`Nacara.Plugin.Literate`
Attributes	`[<RequireQualifiedAccess>]`

F# source files as documentation pages.

A literate file is ordinary F# that compiles: prose in (** … *) comments, everything else code. The page cannot drift from what it documents, because it is what it documents.

It becomes markdown and is handed on, so a literate page gets the same directives, code blocks, highlighting, table of contents and link checking as any other.

Functions and values

create () : IPlugin

F# source files as pages, with the default options.

createWith (configure: LiterateOptions -> LiterateOptions) : IPlugin

F# source files as pages, configured.

Parameter
`configure`	Given the defaults, the options to use. Anything it leaves alone keeps its default.

defaultMeta (value: string) (options: LiterateOptions) : LiterateOptions

Show a "view source" style title on every generated code block.

Parameter
`value`	The value to use.
`options`	The options so far.

defaults: LiterateOptions

extensions (value: string list) (options: LiterateOptions) : LiterateOptions

Extensions treated as literate source.

Parameter
`value`	The value to use.
`options`	The options so far.

frontMatterFormat (options: LiterateOptions) : FrontMatterFormat

How front matter is carried by a source file rather than a markdown one.

A file that starts with --- does not compile, so the same block sits inside a comment. The inner delimiters stay, which is what tells a front matter comment apart from a prose comment.

Parameter
`options`	Which extensions the plugin claims, and what its fences are written in. An `.fsx` writes its front matter in the comment it opens with.

language (value: string) (options: LiterateOptions) : LiterateOptions

Language name used for the generated fences.

Parameter
`value`	The value to use.
`options`	The options so far.

parse (source: string) : LiterateBlock list

Split a source file into what it says and what it does.

Parameter
`source`	The file's text. Lines inside `(* … *)` are prose, everything else is code, and the order of both is kept.

register (site: Site) : Site

Add literate F# to a site.

registerWith (configure: LiterateOptions -> LiterateOptions) (site: Site) : Site

Add literate F# to a site, configured.

Parameter
`configure`	Given the defaults, the options to use. Anything it leaves alone keeps its default.
`site`	The site being described.

toMarkdown (options: LiterateOptions) (blocks: LiterateBlock list) : string

Write the blocks out as the markdown pipeline will read them.

Parameter
`options`	What language the fences are labelled with, and what annotations they carry by default.
`blocks`	Prose and code, in the order the file wrote them.

typeCheck (value: bool) (options: LiterateOptions) : LiterateOptions

Check that the sources compile, with dotnet fsi --typecheck-only.

Parameter
`value`	The value to use.
`options`	The options so far.

typeCheckWhileWatching (value: bool) (options: LiterateOptions) : LiterateOptions

Check while watching too.

Parameter
`value`	The value to use.
`options`	The options so far.