ferron

[ARCHIVED] Ferron is a fast and simple static website generator made with Lua.
Log | Files | Refs | Submodules | README | LICENSE

README.md (3148B)

      1 # Ferron
      2 
      3 Ferron is a static site generator (SSG) crafted with Lua >= 5.3.
      4 
      5 _This documentation is a WIP_!
      6 
      7 ## Installation
      8 
      9 1. Make sure [Lua](https://www.lua.org/) 5.3 (or up), and
     10    [Luarocks](https://luarocks.org/) are installed on your machine.
     11 2. Then:
     12    * `git clone git@github.com:hs0ucy/Ferron.git && cd Ferron`
     13    * `git submodule update --init && git submodule update --recursive --remote`
     14 3. The rest of the installation process is made with the Ferron CLI
     15    (command-line interface) named `cornelius`.
     16 4. So make sure the `cornelius` file have the right permissions to be execute has a script.
     17 5. Otherwise: `chmod a+x cornelius`.
     18 6. After that `./cornelius install`. The `install` will check if Luarocks is
     19    installed on your system and then install all the dependencies with it.
     20 7. If all went well, you are up and ready to create your site.
     21 
     22 ### Dependencies
     23 
     24 * [dkjson](https://luarocks.org/modules/dhkolf/dkjson)
     25 * [LuaFileSysem](https://luarocks.org/modules/hisham/luafilesystem)
     26 * [lustache](https://luarocks.org/modules/olivine-labs/lustache)
     27 * [lua-discount](https://luarocks.org/modules/luarocks/lua-discount)
     28 * [mimetypes](https://luarocks.org/modules/luarocks/mimetypes)
     29 * [inspect](https://luarocks.org/modules/kikito/inspect)
     30 
     31 ## Get Started
     32 
     33 First you need to copy the default site and give it the name of the
     34 website you want to create... to do so just type this and follow the
     35 instructions:
     36 
     37 * `./cornelius start`
     38 
     39 After that with your favorite texteditor or IDE edit the
     40 `config.lua` to meet the needs of your web site:
     41 
     42 * `emacs config.lua`
     43 
     44 ### Architecture of a Ferron website
     45 
     46 * **`sites`**
     47     * .gitignore
     48     * **`sample`**
     49       * **`archetypes`**
     50           * `.gitignore`
     51           * `doc.json`
     52           * `doc.md`
     53       * **`content`**
     54           * `index.json`
     55           * `index.md`
     56       * **`public_html`**
     57           * `.gitignore`
     58       * `config.lua`
     59       * **`static`**
     60       * **`templates`**
     61 
     62 * To simply build a web site:
     63   * `./cornelius build`
     64 * To build a site in development mode:
     65   * `./cornelius build --dev`
     66 
     67 ## Content
     68 
     69 All the content of your site must be markdown (`*.md`) file and
     70 belongs in the `content/` repository. That folder must contains at
     71 least an `index.md` file and an `index.{lua, json}` (optional
     72 now). Lua or JSON files are used for the metadatas of the web pages.
     73 
     74 ## Archetypes
     75 
     76 *Archetypes* are presets files for writing content faster. When you
     77 create a content through an archetype, the basic metadatas of your
     78 markdown file are prefilled and it is put in the right place of the content
     79 tree.
     80 
     81 ### Create a content from an archetype
     82 
     83 * `./cornelius create`
     84 
     85 If it is a success Ferron will output something like this:
     86 
     87 * `- The file '/home/hs0ucy/Documents/Ferron/content/sample/2017/03/this-is-my-first-content-made-from-an-archetype.md' hab been created.`
     88 
     89 Now you can open the file you have created and start to write right
     90 away whithout the need of filling the metadatas.
     91 
     92 ## Templates
     93 
     94 Ferron uses the [mustache template engine](http://mustache.github.io/)
     95 ([for lua](https://github.com/Olivine-Labs/lustache)) to give more
     96 flexibility to build your theme.