Generator

    Fermo

    https://hexdocs.pm/fermo/readme.html

    <div>

    <h1>Fermo</h1>
    <p>A static site generator, build for speed and flexibility.</p>
    <h1>Usage</h1>
    <ol>
    <li>Create an Elixir project:
    </li>
    </ol>
    <pre><code class="sh hljs bash">$ mix new myProject</code></pre>
    <ol start="2">
    <li>Modify <code class="inline">mix.exs</code>
    </li>
    </ol>
    <p>See <a href="#mix-configuration">Mix configuration</a>.</p>
    <ol start="3">
    <li>Get dependencies:
    </li>
    </ol>
    <pre><code class="sh hljs bash">$ mix deps.get</code></pre>
    <ol start="4">
    <li>Create <code class="inline">lib/{{project name}}.ex</code>
    </li>
    </ol>
    <p>See <a href="#configuration">Configuration</a>.</p>
    <ol start="5">
    <li>Build the project:
    </li>
    </ol>
    <pre><code class="sh hljs bash">$ mix fermo.build</code></pre>
    <h1>Capabilities</h1>
    <ul>
    <li>build your projects fast, using all available cores,
    </li>
    <li>handle Middleman-like <a href="#config-defined-pages">config-defined pages</a>,
    </li>
    <li>create <a href="#sitemaps">sitemaps</a>,
    </li>
    <li>handle localized pages,
    </li>
    <li>use an integrated <a href="#webpack-asset-pipeline">Webpack asset pipeline</a>.
    </li>
    </ul>
    <h1>Project Structure</h1>
    <pre><code class="nohighlight makeup elixir"><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">build</span><span class="w">             </span><span class="o">-</span><span class="w"> </span><span class="nc">The</span><span class="w"> </span><span class="n">built</span><span class="w"> </span><span class="n">site</span><span class="w">
    </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">lib</span><span class="w">
    </span><span class="o">|</span><span class="w">   </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">my_project</span><span class="o">.</span><span class="n">ex</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="nc">See</span><span class="w"> </span><span class="p" data-group-id="5603744060-1">[</span><span class="nc">Configuration</span><span class="p" data-group-id="5603744060-1">]</span><span class="p" data-group-id="5603744060-2">(</span><span class="c1">#configuration)</span><span class="w">
    </span><span class="o">|</span><span class="w">   </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">helpers</span><span class="o">.</span><span class="n">ex</span><span class="w">
    </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">mix</span><span class="o">.</span><span class="n">exs</span><span class="w">           </span><span class="o">-</span><span class="w"> </span><span class="nc">See</span><span class="w"> </span><span class="p" data-group-id="5603744060-3">[</span><span class="nc">Mix</span><span class="w"> </span><span class="n">configuration</span><span class="p" data-group-id="5603744060-3">]</span><span class="p" data-group-id="5603744060-4">(</span><span class="c1">#mix-configuration)</span><span class="w">
    </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">priv</span><span class="w">
        </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">locales</span><span class="w">       </span><span class="o">-</span><span class="w"> </span><span class="nc">See</span><span class="w"> </span><span class="p" data-group-id="5603744060-5">[</span><span class="nc">Localization</span><span class="p" data-group-id="5603744060-5">]</span><span class="p" data-group-id="5603744060-6">(</span><span class="c1">#localization)</span><span class="w">
        </span><span class="o">|</span><span class="w">   </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">en</span><span class="o">.</span><span class="n">yml</span><span class="w">
        </span><span class="o">|</span><span class="w">   </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">...</span><span class="w">
        </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">source</span><span class="w">
            </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">javascripts</span><span class="w">
            </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">layouts</span><span class="w">
            </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">localizable</span><span class="w">
            </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">templates</span><span class="w">
            </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">partials</span><span class="w">
            </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">static</span><span class="w">
            </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">stylesheets</span><span class="w">
            </span><span class="o">+</span><span class="o">--</span><span class="w"> </span><span class="n">templates</span></code></pre>
    <h1>Mix Configuration</h1>
    <pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">MyProject.MixProject</span><span class="w"> </span><span class="k" data-group-id="0962998709-1">do</span><span class="w">
      </span><span class="kn">use</span><span class="w"> </span><span class="nc">Mix.Project</span><span class="w">

      </span><span class="kd">def</span><span class="w"> </span><span class="nf">project</span><span class="w"> </span><span class="k" data-group-id="0962998709-2">do</span><span class="w">
        </span><span class="p" data-group-id="0962998709-3">[</span><span class="w">
          </span><span class="n">...</span><span class="w">
          </span><span class="ss">compilers</span><span class="p">:</span><span class="w"> </span><span class="nc">Mix</span><span class="o">.</span><span class="n">compilers</span><span class="p" data-group-id="0962998709-4">(</span><span class="p" data-group-id="0962998709-4">)</span><span class="w"> </span><span class="o">++</span><span class="w"> </span><span class="p" data-group-id="0962998709-5">[</span><span class="ss">:fermo</span><span class="p" data-group-id="0962998709-5">]</span><span class="p">,</span><span class="w">
          </span><span class="n">...</span><span class="w">
          </span><span class="ss">deps</span><span class="p">:</span><span class="w"> </span><span class="n">deps</span><span class="p" data-group-id="0962998709-6">(</span><span class="p" data-group-id="0962998709-6">)</span><span class="w">
        </span><span class="p" data-group-id="0962998709-3">]</span><span class="w">
      </span><span class="k" data-group-id="0962998709-2">end</span><span class="w">

      </span><span class="kd">defp</span><span class="w"> </span><span class="nf">deps</span><span class="w"> </span><span class="k" data-group-id="0962998709-7">do</span><span class="w">
        </span><span class="p" data-group-id="0962998709-8">[</span><span class="w">
          </span><span class="p" data-group-id="0962998709-9">{</span><span class="ss">:fermo</span><span class="p">,</span><span class="w"> </span><span class="s">"~&gt; 0.5.1"</span><span class="p" data-group-id="0962998709-9">}</span><span class="w">
        </span><span class="p" data-group-id="0962998709-8">]</span><span class="w">
      </span><span class="k" data-group-id="0962998709-7">end</span><span class="w">
    </span><span class="k" data-group-id="0962998709-1">end</span></code></pre>
    <h1>Configuration</h1>
    <p>Create a module (under lib) with a name matching your MixProject module defined in
    <code class="inline">[mix.exs](#mix-configuration)</code>.</p>
    <p>This module must implement <code class="inline">build/0</code>, a function that returns an updated
    <code class="inline">[config](#config-object)</code>.</p>
    <pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">MyProject</span><span class="w"> </span><span class="k" data-group-id="3250427627-1">do</span><span class="w">
      </span><span class="na">@moduledoc</span><span class="w"> </span><span class="s">"""
      Documentation for MyProject.
      """</span><span class="w">

      </span><span class="kn">use</span><span class="w"> </span><span class="nc">Fermo</span><span class="w">

      </span><span class="kd">def</span><span class="w"> </span><span class="nf">build</span><span class="w"> </span><span class="k" data-group-id="3250427627-2">do</span><span class="w">
        </span><span class="n">config</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">initial_config</span><span class="p" data-group-id="3250427627-3">(</span><span class="p" data-group-id="3250427627-3">)</span><span class="w">

        </span><span class="p" data-group-id="3250427627-4">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">config</span><span class="p" data-group-id="3250427627-4">}</span><span class="w">
      </span><span class="k" data-group-id="3250427627-2">end</span><span class="w">
    </span><span class="k" data-group-id="3250427627-1">end</span></code></pre>
    <h1>Fermo Invocation</h1>
    <p>The command</p>
    <pre><code class="nohighlight makeup elixir"><span class="kn">use</span><span class="w"> </span><span class="nc">Fermo</span></code></pre>
    <p>prepares the initial <code class="inline">config</code> structure.</p>
    <h2 id="simple-excludes" class="section-heading">
      <a href="#simple-excludes" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
      Simple Excludes
    </h2>

    <p>In order to not have your template files automatically built as <a href="#simple">simple files</a>
    use <code class="inline">:exclude</code>.</p>
    <pre><code class="nohighlight makeup elixir"><span class="w">  </span><span class="kn">use</span><span class="w"> </span><span class="nc">Fermo</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="6042880811-1">%{</span><span class="w">
        </span><span class="ss">exclude</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="6042880811-2">[</span><span class="s">"templates/*"</span><span class="p">,</span><span class="w"> </span><span class="s">"layouts/*"</span><span class="p">,</span><span class="w"> </span><span class="s">"javascripts/*"</span><span class="p">,</span><span class="w"> </span><span class="s">"stylesheets/*"</span><span class="p" data-group-id="6042880811-2">]</span><span class="p">,</span><span class="w">
      </span><span class="p" data-group-id="6042880811-1">}</span></code></pre>
    <h1>Config-defined Pages</h1>
    <p>Most static site generators build one webpage for every source page
    (e.g. Hugo).</p>
    <p>Middleman provides the very powerful but strangely named <code class="inline">proxy</code>,
    which allows you to produce many pages from one template.
    So, if you have a local JSON of YAML file, or even better an online
    CMS, as a source, you can build a page for each of your items
    without having to commit the to your Git repo.</p>
    <p>In Fermo, dynamic, data-based pages are created with the <code class="inline">page</code> method in
    your project configuration's <code class="inline">build/0</code> method.</p>
    <pre><code class="nohighlight makeup elixir"><span class="w">  </span><span class="kd">def</span><span class="w"> </span><span class="nf">build</span><span class="w"> </span><span class="k" data-group-id="3957910708-1">do</span><span class="w">
        </span><span class="n">...</span><span class="w">
        </span><span class="n">foo</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">...</span><span class="w"> </span><span class="c1"># loaded from some external source</span><span class="w">
        </span><span class="n">page</span><span class="p" data-group-id="3957910708-2">(</span><span class="w">
          </span><span class="n">config</span><span class="p">,</span><span class="w">
          </span><span class="s">"templates/foo.html.slim"</span><span class="p">,</span><span class="w">
          </span><span class="s">"/foos/</span><span class="si" data-group-id="3957910708-3">#{</span><span class="n">foo</span><span class="o">.</span><span class="n">slug</span><span class="si" data-group-id="3957910708-3">}</span><span class="s">/index.html"</span><span class="p">,</span><span class="w">
          </span><span class="p" data-group-id="3957910708-4">%{</span><span class="ss">foo</span><span class="p">:</span><span class="w"> </span><span class="n">foo</span><span class="p" data-group-id="3957910708-4">}</span><span class="p">,</span><span class="w">
          </span><span class="p" data-group-id="3957910708-5">%{</span><span class="ss">locale</span><span class="p">:</span><span class="w"> </span><span class="ss">:en</span><span class="p" data-group-id="3957910708-5">}</span><span class="w">
        </span><span class="p" data-group-id="3957910708-2">)</span><span class="w">
        </span><span class="n">...</span><span class="w">
      </span><span class="k" data-group-id="3957910708-1">end</span></code></pre>
    <h1>Templating</h1>
    <p>Currently, Fermo only supports SLIM templates for HTML.</p>
    <p>There are various types of templates:</p>
    <ul>
    <li>simple templates - any templates found under <code class="inline">priv/source</code> will be built. The <code class="inline">partials</code>
    directory is exluded by default - see <a href="#excludes">excludes</a>.
    </li>
    <li>page templates - used with <a href="#config-defined-pages">config-defined pages</a>,
    </li>
    <li>partials - used from other templates,
    </li>
    <li>localized - build for each configured locale. See <a href="#localization">localization</a>
    </li>
    </ul>
    <h2 id="parameters" class="section-heading">
      <a href="#parameters" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
      Parameters
    </h2>

    <p>Top level pages are called with the following parameters:</p>
    <ul>
    <li><code class="inline">params</code> - the parameters passed directly to the template or partial,
    </li>
    <li><code class="inline">context</code> - hash of contextual information.
    </li>
    </ul>
    <h3 id="context" class="section-heading">
      <a href="#context" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
      Context
    </h3>

    <ul>
    <li><code class="inline">:env</code> - the application environment,
    </li>
    <li><code class="inline">:module</code> - the module of the compiled template,
    </li>
    <li><code class="inline">:template</code> - the top-level page or partial template pathname, with path
    relative to the source root,
    </li>
    <li><code class="inline">:page</code> - see below.
    </li>
    </ul>
    <h3 id="page" class="section-heading">
      <a href="#page" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
      Page
    </h3>

    <p>Information about the top-level page.</p>
    <ul>
    <li><code class="inline">:template</code> - the template path and name relative to the source root,
    </li>
    <li><code class="inline">:target</code> - the path of the generated file,
    </li>
    <li><code class="inline">:path</code> - the online path of the page,
    </li>
    <li><code class="inline">:params</code> - the parameters passed to the template,
    </li>
    <li><code class="inline">:options</code> - other options, e.g. the locale.
    </li>
    </ul>
    <h2 id="partials" class="section-heading">
      <a href="#partials" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
      Partials
    </h2>

    <p>Partials are also called with the same 2 parameters, but the values in <code class="inline">:page</code>
    are those of the top-level page, not the partial itself.</p>
    <h1>Associated Libraries</h1>
    <ul>
    <li><a href="https://hexdocs.pm/datocms_graphql_client.html" title="">DatoCMS GraphQL Client</a>
    </li>
    <li><a href="https://hexdocs.pm/fermo_helpers/FermoHelpers.html" title="">FermoHelpers</a>
    </li>
    </ul>
    <h1>Localization</h1>
    <p>If you pass an <code class="inline">:i18n</code> key with a list of locales to Fermo,
    your locale files will be loaded at build time and
    files under <code class="inline">localizable</code> will be built for each locale.</p>
    <pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">MyProject</span><span class="w"> </span><span class="k" data-group-id="3071655159-1">do</span><span class="w">
      </span><span class="na">@moduledoc</span><span class="w"> </span><span class="s">"""
      Documentation for MyProject.
      """</span><span class="w">

      </span><span class="kn">use</span><span class="w"> </span><span class="nc">Fermo</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="3071655159-2">%{</span><span class="w">
        </span><span class="n">...</span><span class="w">
        </span><span class="ss">i18n</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="3071655159-3">[</span><span class="ss">:en</span><span class="p">,</span><span class="w"> </span><span class="ss">:fr</span><span class="p" data-group-id="3071655159-3">]</span><span class="w">
      </span><span class="p" data-group-id="3071655159-2">}</span><span class="w">

      </span><span class="n">...</span><span class="w">
    </span><span class="k" data-group-id="3071655159-1">end</span></code></pre>
    <h2 id="localized_paths" class="section-heading">
      <a href="#localized_paths" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
      <code class="inline">:localized_paths</code>
    </h2>

    <p>Fermo can optionally create a mapping of translated paths for any
    page.</p>
    <p>This allows you to easily manage language switching UIs and alternate
    language meta tags.</p>
    <p>To activate localized_paths, you need to pass a flag in your initial
    config:</p>
    <pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">MyProject</span><span class="w"> </span><span class="k" data-group-id="9731992206-1">do</span><span class="w">
      </span><span class="kn">use</span><span class="w"> </span><span class="nc">Fermo</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="9731992206-2">%{</span><span class="w">
        </span><span class="n">...</span><span class="w">
        </span><span class="ss">i18n</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="9731992206-3">[</span><span class="ss">:en</span><span class="p">,</span><span class="w"> </span><span class="ss">:fr</span><span class="p" data-group-id="9731992206-3">]</span><span class="p">,</span><span class="w">
        </span><span class="ss">path_map</span><span class="p">:</span><span class="w"> </span><span class="no">true</span><span class="p">,</span><span class="w">
        </span><span class="n">...</span><span class="w">
      </span><span class="p" data-group-id="9731992206-2">}</span><span class="w">

      </span><span class="n">...</span><span class="w">
    </span><span class="k" data-group-id="9731992206-1">end</span></code></pre>
    <p>Then ensure you pass an <code class="inline">:id</code> and <code class="inline">:locale</code> in the options parameter
    of your Fermo.page/5 calls:</p>
    <pre><code class="nohighlight makeup elixir"><span class="nc">Fermo</span><span class="o">.</span><span class="n">page</span><span class="p" data-group-id="4975382827-1">(</span><span class="w">
      </span><span class="n">config</span><span class="p">,</span><span class="w">
      </span><span class="s">"templates/my_template.html.slim"</span><span class="p">,</span><span class="w">
      </span><span class="s">"/posts/</span><span class="si" data-group-id="4975382827-2">#{</span><span class="n">post</span><span class="o">.</span><span class="n">slug</span><span class="si" data-group-id="4975382827-2">}</span><span class="s">/index.html"</span><span class="p">,</span><span class="w">
      </span><span class="p" data-group-id="4975382827-3">%{</span><span class="ss">post</span><span class="p">:</span><span class="w"> </span><span class="n">post</span><span class="p" data-group-id="4975382827-3">}</span><span class="p">,</span><span class="w">
      </span><span class="p" data-group-id="4975382827-4">%{</span><span class="ss">locale</span><span class="p">:</span><span class="w"> </span><span class="ss">:fr</span><span class="p">,</span><span class="w"> </span><span class="ss">id</span><span class="p">:</span><span class="w"> </span><span class="s">"post-</span><span class="si" data-group-id="4975382827-5">#{</span><span class="n">post</span><span class="o">.</span><span class="n">id</span><span class="si" data-group-id="4975382827-5">}</span><span class="s">"</span><span class="p" data-group-id="4975382827-4">}</span><span class="w">
    </span><span class="p" data-group-id="4975382827-1">)</span></code></pre>
    <p>When you do this, Fermo will collect together all pages with the same <code class="inline">:id</code>
    so when your template is called, it will have a <code class="inline">:localized_paths</code> Map available:</p>
    <pre><code class="nohighlight makeup elixir"><span class="p" data-group-id="2342907250-1">%{</span><span class="w">
      </span><span class="n">...</span><span class="w">
      </span><span class="ss">localized_paths</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="2342907250-2">%{</span><span class="w">
        </span><span class="ss">en</span><span class="p">:</span><span class="w"> </span><span class="s">"/posts/about-localization"</span><span class="p">,</span><span class="w">
        </span><span class="ss">fr</span><span class="p">:</span><span class="w"> </span><span class="s">"/posts/a-propos-de-la-localisation"</span><span class="p">,</span><span class="w">
      </span><span class="p" data-group-id="2342907250-2">}</span><span class="w">
    </span><span class="p" data-group-id="2342907250-1">}</span></code></pre>
    <p>You can then use <code class="inline">:localized_paths</code> to build create links between
    the different language versions of a page.</p>
    <p>You can do the same for non-dynamic localized pages too, by indicating
    the id in the template's frontmatter:</p>
    <pre><code class="slim hljs">---
    id: my-localized-page
    ---</code></pre>
    <h1>Middleman to Fermo</h1>
    <p>Fermo was created as an improvement on Middleman, so its defaults
    tend to be the same its progenitor.</p>
    <p>See <a href="MiddlemanToFermo.md">here</a>.</p>
          <footer class="footer">
            <p>
              <span class="line">
                Built using
                <a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener">ExDoc</a> (v0.21.3),
              </span>
              <span class="line">
                designed by
                <a href="https://twitter.com/dignifiedquire" target="_blank" rel="noopener" title="@dignifiedquire">Friedel Ziegelmayer</a> for the <a href="https://elixir-lang.org" title="Elixir" target="_blank">Elixir programming language</a>.
              </span>
            </p>
            <p>
              <button class="line footer-button display-shortcuts-help">
                Display keyboard shortcuts
              </button>
              <button class="line footer-button night-mode-toggle">
                Toggle night mode
              </button>
              <button class="line footer-button display-quick-switch">
                Go to a HexDocs package
              </button>
              <button class="line footer-button tooltips-toggle" data-is-disabled="false">
                <span class="tooltips-option-disable">Disable tooltips</span>
                <span class="tooltips-option-enable">Enable tooltips</span>
              </button>
            </p>
          </footer>
        <div id="tooltip" style="left: 90.4667px; right: auto; top: 416px;">
      <div class="tooltip-body"></div>
      
    <iframe class="tooltip-iframe" src="/fermo/readme.html?hint=true#mix-configuration" sandbox="allow-scripts allow-same-origin"></iframe></div>
    </div>

    ;