<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>5. Custom pre- and post-processing · Literate.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL="."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="assets/documenter.js"></script><scriptsrc="siteinfo.js"></script><scriptsrc="../versions.js"></script><linkhref="assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="index.html"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="fileformat.html"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="outputformats.html"><strong>4.</strong> Output Formats</a></li><liclass="current"><aclass="toctext"href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a><ulclass="internal"></ul></li><li><aclass="toctext"href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><li><aclass="toctext"href="generated/example.html"><strong>7.</strong> Example</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/customprocessing.md"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>5. Custom pre- and post-processing</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="Custom-pre-and-post-processing-1"href="#Custom-pre-and-post-processing-1"><strong>5.</strong> Custom pre- and post-processing</a></h1><p>Since all packages are different, and may have different demands on how to create a nice example for the documentation it is important that the package maintainer does not feel limited by the by default provided syntax that this package offers. While you can generally come a long way by utilizing <ahref="fileformat.html#Filtering-Lines-1">line filtering</a> there might be situations where you need to manually hook into the generation and change things. In Literate this is done by letting the user supply custom pre- and post-processing functions that may do transformation of the content.</p><p>All of the generators (<ahref="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>, <ahref="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a> and <ahref="outputformats.html#Literate.script"><code>Literate.script</code></a>) accepts <code>preprocess</code> and <code>postprocess</code> keyword arguments. The default "transformation" is the <code>identity</code> function. The input to the transformation functions is a <code>String</code>, and the output should be the transformed <code>String</code>.</p><p><code>preprocess</code> is sent the raw input that is read from the source file (<ahref="pipeline.html#Pre-processing-1">modulo the default line ending transformation</a>). <code>postprocess</code> is given different things depending on the output: For markdown and script output <code>postprocess</code> is given the content <code>String</code> just before writing it to the output file, but for notebook output <code>postprocess</code> is given the dictionary representing the notebook, since, in general, this is more useful.</p><p>As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a <code>preprocess</code> function that splices the date into the source for us. Consider the following source file:</p><pre><codeclass="language-julia"># # Example
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>5. Custom pre- and post-processing · Literate.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL="."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="assets/documenter.js"></script><scriptsrc="siteinfo.js"></script><scriptsrc="../versions.js"></script><linkhref="assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><ahref="index.html"><imgclass="logo"src="assets/logo.png"alt="Literate.jl logo"/></a><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="index.html"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="fileformat.html"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="outputformats.html"><strong>4.</strong> Output Formats</a></li><liclass="current"><aclass="toctext"href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a><ulclass="internal"></ul></li><li><aclass="toctext"href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><li><aclass="toctext"href="generated/example.html"><strong>7.</strong> Example</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/customprocessing.md"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>5. Custom pre- and post-processing</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="Custom-pre-and-post-processing-1"href="#Custom-pre-and-post-processing-1"><strong>5.</strong> Custom pre- and post-processing</a></h1><p>Since all packages are different, and may have different demands on how to create a nice example for the documentation it is important that the package maintainer does not feel limited by the by default provided syntax that this package offers. While you can generally come a long way by utilizing <ahref="fileformat.html#Filtering-Lines-1">line filtering</a> there might be situations where you need to manually hook into the generation and change things. In Literate this is done by letting the user supply custom pre- and post-processing functions that may do transformation of the content.</p><p>All of the generators (<ahref="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>, <ahref="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a> and <ahref="outputformats.html#Literate.script"><code>Literate.script</code></a>) accepts <code>preprocess</code> and <code>postprocess</code> keyword arguments. The default "transformation" is the <code>identity</code> function. The input to the transformation functions is a <code>String</code>, and the output should be the transformed <code>String</code>.</p><p><code>preprocess</code> is sent the raw input that is read from the source file (<ahref="pipeline.html#Pre-processing-1">modulo the default line ending transformation</a>). <code>postprocess</code> is given different things depending on the output: For markdown and script output <code>postprocess</code> is given the content <code>String</code> just before writing it to the output file, but for notebook output <code>postprocess</code> is given the dictionary representing the notebook, since, in general, this is more useful.</p><p>As an example, lets say we want to splice the date of generation into the output. We could of course update our source file before generating the docs, but we could instead use a <code>preprocess</code> function that splices the date into the source for us. Consider the following source file:</p><pre><codeclass="language-julia"># # Example
# This example was generated DATEOFTODAY
# This example was generated DATEOFTODAY
x = 1 // 3</code></pre><p>where <code>DATEOFTODAY</code> is a placeholder, to make it easier for our <code>preprocess</code> function to find the location. Now, lets define the <code>preprocess</code> function, for example</p><pre><codeclass="language-julia">function update_date(content)
x = 1 // 3</code></pre><p>where <code>DATEOFTODAY</code> is a placeholder, to make it easier for our <code>preprocess</code> function to find the location. Now, lets define the <code>preprocess</code> function, for example</p><pre><codeclass="language-julia">function update_date(content)
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>6. Interaction with Documenter.jl · Literate.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL="."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="assets/documenter.js"></script><scriptsrc="siteinfo.js"></script><scriptsrc="../versions.js"></script><linkhref="assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="index.html"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="fileformat.html"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><liclass="current"><aclass="toctext"href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a><ulclass="internal"></ul></li><li><aclass="toctext"href="generated/example.html"><strong>7.</strong> Example</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/documenter.md"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>6. Interaction with Documenter.jl</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="Interaction-with-Documenter-1"href="#Interaction-with-Documenter-1"><strong>6.</strong> Interaction with Documenter.jl</a></h1><p>Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (<ahref="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>, <ahref="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a> and <ahref="outputformats.html#Literate.script"><code>Literate.script</code></a>) supports a keyword argument <code>documenter</code> that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set <code>documenter = true</code>:</p><h3><aclass="nav-anchor"id="[Literate.markdown](@ref):-1"href="#[Literate.markdown](@ref):-1"><ahref="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>:</a></h3><ul><li>The default code fence will change from<pre><codeclass="language-none">```julia
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>6. Interaction with Documenter.jl · Literate.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL="."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="assets/documenter.js"></script><scriptsrc="siteinfo.js"></script><scriptsrc="../versions.js"></script><linkhref="assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><ahref="index.html"><imgclass="logo"src="assets/logo.png"alt="Literate.jl logo"/></a><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="index.html"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="fileformat.html"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><liclass="current"><aclass="toctext"href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a><ulclass="internal"></ul></li><li><aclass="toctext"href="generated/example.html"><strong>7.</strong> Example</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/documenter.md"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>6. Interaction with Documenter.jl</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="Interaction-with-Documenter-1"href="#Interaction-with-Documenter-1"><strong>6.</strong> Interaction with Documenter.jl</a></h1><p>Literate can be used for any purpose, it spits out regular markdown files, and notebooks. Typically, though, these files will be used to render documentation for your package. The generators (<ahref="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>, <ahref="outputformats.html#Literate.notebook"><code>Literate.notebook</code></a> and <ahref="outputformats.html#Literate.script"><code>Literate.script</code></a>) supports a keyword argument <code>documenter</code> that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So lets take a look at what will happen if we set <code>documenter = true</code>:</p><h3><aclass="nav-anchor"id="[Literate.markdown](@ref):-1"href="#[Literate.markdown](@ref):-1"><ahref="outputformats.html#Literate.markdown"><code>Literate.markdown</code></a>:</a></h3><ul><li>The default code fence will change from<pre><codeclass="language-none">```julia
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>2. File Format · Literate.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL="."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="assets/documenter.js"></script><scriptsrc="siteinfo.js"></script><scriptsrc="../versions.js"></script><linkhref="assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="index.html"><strong>1.</strong> Introduction</a></li><liclass="current"><aclass="toctext"href="fileformat.html"><strong>2.</strong> File Format</a><ulclass="internal"><li><aclass="toctext"href="#Syntax-1"><strong>2.1.</strong> Syntax</a></li><li><aclass="toctext"href="#Filtering-Lines-1"><strong>2.2.</strong> Filtering Lines</a></li><li><aclass="toctext"href="#Default-Replacements-1"><strong>2.3.</strong> Default Replacements</a></li></ul></li><li><aclass="toctext"href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><li><aclass="toctext"href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><li><aclass="toctext"href="generated/example.html"><strong>7.</strong> Example</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="fileformat.html"><strong>2.</strong> File Format</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/fileformat.md"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>2. File Format</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="**2.**-File-Format-1"href="#**2.**-File-Format-1"><strong>2.</strong> File Format</a></h1><p>The source file format for Literate is a regular, commented, julia (<code>.jl</code>) scripts. The idea is that the scripts also serve as documentation on their own and it is also simple to include them in the test-suite, with e.g. <code>include</code>, to make sure the examples stay up do date with other changes in your package.</p><h2><aclass="nav-anchor"id="Syntax-1"href="#Syntax-1"><strong>2.1.</strong> Syntax</a></h2><p>The basic syntax is simple:</p><ul><li>lines starting with <code>#</code> are treated as markdown,</li><li>all other lines are treated as julia code.</li></ul><p>Leading whitespace is allowed before <code>#</code>, but it will be removed when generating the output. Since <code>#</code>-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use <code>##</code>, which will render as <code>#</code> in the output.</p><p>Lets look at a simple example:</p><pre><codeclass="language-julia"># # Rational numbers
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>2. File Format · Literate.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL="."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="assets/documenter.js"></script><scriptsrc="siteinfo.js"></script><scriptsrc="../versions.js"></script><linkhref="assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><ahref="index.html"><imgclass="logo"src="assets/logo.png"alt="Literate.jl logo"/></a><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="index.html"><strong>1.</strong> Introduction</a></li><liclass="current"><aclass="toctext"href="fileformat.html"><strong>2.</strong> File Format</a><ulclass="internal"><li><aclass="toctext"href="#Syntax-1"><strong>2.1.</strong> Syntax</a></li><li><aclass="toctext"href="#Filtering-Lines-1"><strong>2.2.</strong> Filtering Lines</a></li><li><aclass="toctext"href="#Default-Replacements-1"><strong>2.3.</strong> Default Replacements</a></li></ul></li><li><aclass="toctext"href="pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><li><aclass="toctext"href="documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><li><aclass="toctext"href="generated/example.html"><strong>7.</strong> Example</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="fileformat.html"><strong>2.</strong> File Format</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/docs/src/fileformat.md"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>2. File Format</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="**2.**-File-Format-1"href="#**2.**-File-Format-1"><strong>2.</strong> File Format</a></h1><p>The source file format for Literate is a regular, commented, julia (<code>.jl</code>) scripts. The idea is that the scripts also serve as documentation on their own and it is also simple to include them in the test-suite, with e.g. <code>include</code>, to make sure the examples stay up do date with other changes in your package.</p><h2><aclass="nav-anchor"id="Syntax-1"href="#Syntax-1"><strong>2.1.</strong> Syntax</a></h2><p>The basic syntax is simple:</p><ul><li>lines starting with <code>#</code> are treated as markdown,</li><li>all other lines are treated as julia code.</li></ul><p>Leading whitespace is allowed before <code>#</code>, but it will be removed when generating the output. Since <code>#</code>-lines is treated as markdown we can not use that for regular julia comments, for this you can instead use <code>##</code>, which will render as <code>#</code> in the output.</p><p>Lets look at a simple example:</p><pre><codeclass="language-julia"># # Rational numbers
#
#
# In julia rational numbers can be constructed with the `//` operator.
# In julia rational numbers can be constructed with the `//` operator.
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>7. Example · Literate.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL=".."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="../assets/documenter.js"></script><scriptsrc="../siteinfo.js"></script><scriptsrc="../../versions.js"></script><linkhref="../assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="../search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="../index.html"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="../fileformat.html"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="../pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="../outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="../customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><li><aclass="toctext"href="../documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><liclass="current"><aclass="toctext"href="example.html"><strong>7.</strong> Example</a><ulclass="internal"></ul></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="example.html"><strong>7.</strong> Example</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>7. Example</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="**7.**-Example-1"href="#**7.**-Example-1"><strong>7.</strong> Example</a></h1><p>This is an example generated with Literate based on this source file: <ahref="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl"><code>example.jl</code></a>. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: <ahref="https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/latest/generated/example.ipynb"><code>example.ipynb</code></a>, and the plain script output can be found here: <ahref="example.jl"><code>example.jl</code></a>.</p><p>It is recommended to have the <ahref="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl">source file</a> available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.</p><h3><aclass="nav-anchor"id="Basic-syntax-1"href="#Basic-syntax-1">Basic syntax</a></h3><p>The basic syntax for Literate is simple, lines starting with <code>#</code> is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:</p><div><pre><codeclass="language-julia">x = 1//3
<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>7. Example · Literate.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL=".."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="../assets/documenter.js"></script><scriptsrc="../siteinfo.js"></script><scriptsrc="../../versions.js"></script><linkhref="../assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><ahref="../index.html"><imgclass="logo"src="../assets/logo.png"alt="Literate.jl logo"/></a><h1>Literate.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"id="search-form"action="../search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="../index.html"><strong>1.</strong> Introduction</a></li><li><aclass="toctext"href="../fileformat.html"><strong>2.</strong> File Format</a></li><li><aclass="toctext"href="../pipeline.html"><strong>3.</strong> Processing pipeline</a></li><li><aclass="toctext"href="../outputformats.html"><strong>4.</strong> Output Formats</a></li><li><aclass="toctext"href="../customprocessing.html"><strong>5.</strong> Custom pre- and post-processing</a></li><li><aclass="toctext"href="../documenter.html"><strong>6.</strong> Interaction with Documenter.jl</a></li><liclass="current"><aclass="toctext"href="example.html"><strong>7.</strong> Example</a><ulclass="internal"></ul></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="example.html"><strong>7.</strong> Example</a></li></ul><aclass="edit-page"href="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>7. Example</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="**7.**-Example-1"href="#**7.**-Example-1"><strong>7.</strong> Example</a></h1><p>This is an example generated with Literate based on this source file: <ahref="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl"><code>example.jl</code></a>. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: <ahref="https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/latest/generated/example.ipynb"><code>example.ipynb</code></a>, and the plain script output can be found here: <ahref="example.jl"><code>example.jl</code></a>.</p><p>It is recommended to have the <ahref="https://github.com/fredrikekre/Literate.jl/blob/master/examples/example.jl">source file</a> available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.</p><h3><aclass="nav-anchor"id="Basic-syntax-1"href="#Basic-syntax-1">Basic syntax</a></h3><p>The basic syntax for Literate is simple, lines starting with <code>#</code> is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:</p><div><pre><codeclass="language-julia">x = 1//3
y = 2//5</code></pre><pre><codeclass="language-none">2//5</code></pre></div><p>In markdown sections we can use markdown syntax. For example, we can write <em>text in italic font</em>, <strong>text in bold font</strong> and use <ahref="https://www.youtube.com/watch?v=dQw4w9WgXcQ">links</a>.</p><p>It is possible to filter out lines depending on the output using the <code>#md</code>, <code>#nb</code>, <code>#jl</code> and <code>#src</code> tags (see <ahref="../fileformat.html#Filtering-Lines-1">Filtering Lines</a>):</p><ul><li>This line starts with <code>#md</code> and is thus only visible in the markdown output.</li></ul><p>The source file is parsed in chunks of markdown and code. Starting a line with <code>#-</code> manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert <code>#-</code> in between. These two code blocks will now end up in different <code>@example</code>-blocks in the markdown output, and two different notebook cells in the notebook output.</p><div><pre><codeclass="language-julia">x + y</code></pre><pre><codeclass="language-none">11//15</code></pre></div><div><pre><codeclass="language-julia">x * y</code></pre><pre><codeclass="language-none">2//15</code></pre></div><h3><aclass="nav-anchor"id="Output-Capturing-1"href="#Output-Capturing-1">Output Capturing</a></h3><p>Code chunks are by default placed in Documenter <code>@example</code> blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the <code>execute</code> keyword argument is set to true. Output to <code>stdout</code>/<code>stderr</code> is also captured.</p><div><pre><codeclass="language-julia">function foo()
y = 2//5</code></pre><pre><codeclass="language-none">2//5</code></pre></div><p>In markdown sections we can use markdown syntax. For example, we can write <em>text in italic font</em>, <strong>text in bold font</strong> and use <ahref="https://www.youtube.com/watch?v=dQw4w9WgXcQ">links</a>.</p><p>It is possible to filter out lines depending on the output using the <code>#md</code>, <code>#nb</code>, <code>#jl</code> and <code>#src</code> tags (see <ahref="../fileformat.html#Filtering-Lines-1">Filtering Lines</a>):</p><ul><li>This line starts with <code>#md</code> and is thus only visible in the markdown output.</li></ul><p>The source file is parsed in chunks of markdown and code. Starting a line with <code>#-</code> manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert <code>#-</code> in between. These two code blocks will now end up in different <code>@example</code>-blocks in the markdown output, and two different notebook cells in the notebook output.</p><div><pre><codeclass="language-julia">x + y</code></pre><pre><codeclass="language-none">11//15</code></pre></div><div><pre><codeclass="language-julia">x * y</code></pre><pre><codeclass="language-none">2//15</code></pre></div><h3><aclass="nav-anchor"id="Output-Capturing-1"href="#Output-Capturing-1">Output Capturing</a></h3><p>Code chunks are by default placed in Documenter <code>@example</code> blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the <code>execute</code> keyword argument is set to true. Output to <code>stdout</code>/<code>stderr</code> is also captured.</p><div><pre><codeclass="language-julia">function foo()
println("This string is printed to stdout.")
println("This string is printed to stdout.")
autodocs
7 years ago
