Creating your first site

On this page

Minimal configuration
Using a custom template
Tags on your Markdown files
Looking for more examples?
Reserved configuration

Minimal configuration #

Start creating your first site following the next steps:

Create the configuration file : _configuration.yaml:

title: Your new static site

Create the a Markdown formatted file with your content: index.md:

# {{title}}

Welcome to your new static site generated using **Lighthouse**!

Execute Lighthouse command to generate the site:

lighthouse (<path-to-site-directory>)

Check the new _site directory that contains your new generated site. The index.html should have this content:

<h1>Your new static site</h1>

Welcome to your new static site generated using <b>Lighthouse</b>!

Using a custom template #

It is possible to set a custom template file on _configuration.yml file, or on the yaml header inside any md file. The template to be used has to be used on a html file that needs to be referenced on the required configuration path as can be seen bellow.

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <title>{{title}}</title>
</head>

<body>
  {{body}}
</body>

</html>

document:
  template: path/to/your/template/file.html

info Info Remember to include the special {{body}} tag inside your template, so the content of the processed md file that use this template can include their content there.

Tags on your Markdown files #

It is possible to include multiple tags on your html template files and md files. This is the list of tags that Lighthouse supports now:

foreach
if
<variables>
include
generate
ignore

foreach tag #

This tag is in charge of the expansion of your template. It allows to repeat a given number of time a section of your template or your document, using different variables to do it.

To use it on your documents:

{{foreach <variable> <list>}}{{foreach-end}}
{{foreach <variable> <list>}}{{foreach-end <list>}}

list element is a collection of elements on your configuration. variable is a private-scope variable you declare to use inside each loop, and allows you to access the element of the collection the loop is processing on each iteration.

It is possible to create nested foreach expressions, so you can create more complex structures.

foreach loops are processed from out to in, what means that the more external loops are processed first. This is required because of the variable replacements done, as internal loops may reference variables declared on a external structure.

warning Warning Pay attention there are two ways of declaring a foreach. The second way allows to mark the closing mark to know the end of a given loop. This alternative way is mandatory to be used when declaring nested loops, as it allows the processor to detect the closing tags for each level.

if tag #

The aim of this tag is the selection of different blocks on your template or document. Depending of the value of a given variable, one side or the other of the block is used.

To use it on your document:

{{if <variable>}}<your-code>{{if-end}}
{{if <variable>}}<your-code>{{if-end <variable>}}
{{if <variable>}}<your-code>{{if-else}}<alternative-code>{{if-end}}
{{if <variable>}}<your-code>{{if-else}}<alternative-code>{{if-end <variable>}}

The value of variable is used to select the section of the tag. It is used Javascript to evaluate the variable, so the same conditions are applied for the truthfulness or nullability of an expression.

It is possible to create nested if expressions, so you can create more complex structures.

On the contrary of foreach tags, if are processed from in to out. This means that internal conditions are processed first.

info Info Following the same approach as on foreach loops, there are two ways of declaring an if. The second way allows to mark the closing mark to know the end of a given loop using the same variable as a tag. On this case, tags are optional, and you may use them if you wish to improve readability.

variable tags #

It is possible to create tag with any given value and use them on any part of the template or document. If the variable is not found on the configuration, a log will be printed on the console and it will replaced by an empty string.

info Info If the debug mode is active, not found variables will be replaced by an error template on the output document.

Including external files #

To include static content from other files on your template or document, the include tag can be used.

To use it on your document:

{{include <path-to-your-file>}}
{{i <path-to-your-file>}}

This tag can be also used on Markdown header section:

---
title: Include a file content
custom:
  path:
    include: {{include _include/file_a.md}}
---

# {{title}}

{{i _include/file_b.html}}

{{custom.path.include}}

This tag will load the content of the given file and will be replaced with the text that is inside the file. This is not only limited to html or md files, any text file can be loaded using this method.

Generating code using Javascript #

There is also ways to generate dynamic content to your templates or documents. For that purpose the generate tag is here.

To use it on your document:

{{generate <path-to-your-js-file>}}
{{g <path-to-your-js-file>}}
{{generate <path-to-your-js-file>::<function-to-call>(<parameters>)}}
{{g <path-to-your-js-file>::<function-to-call>(<parameters>)}}

Example of usage:

File file_a.js:

function main() {
  return "This content comes from JS code.";
}

File file_b.js:

function execute(value) {
  return value.toUpperCase();
}

---
title: Generate content using JS
custom:
  path:
    generate: "{{generate file_a.js}}"
  variable: This should appear in capital letters
---

# {{title}}

{{g file_b.js::execute({{custom.variable}})}}

{{custom.path.generate}}

info Info If not call function is set on the tag, main function with no parameters will be invoked.

Ignoring Lighthouse tags #

Sometimes, it may be useful to skip the processing of some of the Lighthouse tags, as an example: this page. Here, we are showing some examples of how to use tags on different scenarios, but we don't want the site generator to process them.

For that purpose, the ignore tag is there. It allows to skip the processing of all Lighthouse tags between the opening and closing tags.

To use it on your document:

{{ignore}}<section-to-ignore>{{ignore-end}}

Example of usage:

{{ignore}}
{{ignore-variable-replacements}}
{{ignore-end}}

After processing, this code will be turned into:

{{ignore-variable-replacements}}

As it can be seen, ignore block is discarded, and its content is kept.

info Info Ignore tag is used massively on this documentation page, as tag examples need to be kept without processing.

Looking for more examples? #

If you need more examples or use cases, you may want to go to the test section, where most of the scenarios to generate sites are covered. You can discover some more complex usages of Lighthouse there.

Reserved configuration #

As the user has full freedom to set the Markdown configuration on the yaml header, it has to be taken into account that some configuration paths are used internally by the application.

Make sure to don't override them by mistake. This is the list of them and a short description of their use:

site:
  base_url // Root page address where the site is being published
document:
  template // HTML Template the file used for generating the output files
  output:
    path // Alternative path inside `output.directory` where the converted file will be stored
    name // Alternative converted file name
  headers:
    generate_ids // Enables if IDs are generated and headers are converted to anchors on HTML output files
    permalinks:
      enabled // Enables the display of permalinks next to each of the headers
      symbol // Specifies the symbols used on permalinks
  toc:
    enabled // Enables TOC
    levels // Array to configure the visible levels of the TOC
    header // Text to be included before the TOC
    footer // Text to be included after the TOC
output:
  directory // Directory where the converted files will be stored
  copy_files // Array of files (and destination name) to be copied to the output file
  sitemap:
    enabled // Indicates if the sitemap is generated
    lastmod // Date and time to set on the sitemap.xml entries. Suggested format: "YYYY-mm-ddTHH:MM:ss+00:00". Sets execution time if empty
    extra_links // List of resources that will be added additionally to the site map
processing_file: // Path to the current MD file the application is processing. Not present if processing non MD files
  path // Complete path to the file, including name and extension
  name // Name of the file is being converted
  extension // Extension of the file is being converted
execute:
  before_all // Array of scripts to execute before starting processing files and directories
  before_each // Array of scripts to execute before processing the file where it is set
  before_save_each // Array of scripts to execute before saving the generated file
  after_each // Array of scripts to execute after processing the file where it is set
  after_all // Array of scripts to execute after processing all files and directories

On this page

Minimal configuration
Using a custom template
Tags on your Markdown files
Looking for more examples?
Reserved configuration