Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/leapcode/amber

Flexible static website generator, with good support for localization and navigation.
https://github.com/leapcode/amber

Last synced: 5 days ago
JSON representation

Flexible static website generator, with good support for localization and navigation.

Awesome Lists containing this project

README 

        
Amber

===================================



Amber is a super simple and flexible static website generator, with good

support for localization and navigation.



This is still experimental code.



Amber has much in common with other static page generators, but has several

features that make it unique:



* I18n: Primary focus is on very good multi-lingual and localization support.

  By using a bunch of Apache tricks, Amber is able to create static websites

  which work   more like dynamic sites when it comes to selecting the

  appropriate locale.

* Inheritance: Properties are inherited in the page hierarchy.

* TOC: Support for table of contents (including inserting TOC into other pages,

  and TOC generation from pages generated by a combination of partials and

  different markup languages).

* Flexible: Ability to set custom page path aliases, render partials, rich

  navigation, and so on.

* Wiki Linking: Built in wiki-linking, with dead link detection and hierarchical paths.



Amber allows ERB (ruby code) in all page markup types, making it unsuitable for

any website where you do not trust the source of the page text.



Installation

---------------------------------



Installing from gem:



    sudo apt-get install rubygems ruby-dev build-essential

    sudo gem install amber



Alternately, you can run directly from source:



    sudo apt install ruby ruby-dev

    sudo gem install bundler

    cd ~

    git clone https://github.com/leapcode/amber

    cd amber

    mkdir vendor

    bundle config set --local path "vendor"

    bundle

    export GEM_HOME="~/amber/vendor/ruby/2.7.0/"

    export PATH="~/amber/bin:$PATH"



Directory structure

---------------------------------



A simple website has three main folders, `amber`, `pages`, and `public`. For

example:



    mysite/

      amber/

        config.rb

        locales/

          en.yml

        menu.txt

        layouts/

          default.haml

      pages/

        page1.en.md

        page1.de.md

      public/

        page1/

          en.html

          de.html



The `public` folder is automatically generated from the `pages` folder.

Configuration lives in `amber`.



Menu

---------------------------------



A page does not show up in the navigation unless it appears in

`amber/menu.txt`.



The order in menu.txt determines the order in the navigation. For example:



    aaa

    ccc

    bbb



Page hierarchy is represented by two spaces:



    aaa

      bbb

      ccc

        ddd

    eee



The items in the menu.txt file must match the names of the pages (the filename

with the suffix and locale stripped away).



Supported syntaxes

---------------------------------



Depending the the file extension, the file with be parsed like so:



    .haml       -- HAML

    .md         -- Markdown

    .markdown   -- Markdown

    .text       -- Textile

    .textile    -- Textile

    .html       -- HTML



You can use the native linking method for each markup, or you can use the

Amber link method:



    [[label -> page-name]]

    or

    [[label => page-name]]

    or

    [[label -> absolute-url]]

    or

    [[page-name]]



In these examples, `page-name` can be the name of the page, optionally

qualified by some context. For example, if you had two pages called

`security`, you could link to `[[chat/security]]` or `[[email/security]]`.



This double bracket link notation will automatically find the right

path for the page with the specified name. Also, Amber will warn you if the page

name is missing and it will ensure that the link is created with the correct

language prefix. In haml, you can get the same effect using

`link 'label' => 'page-name'`



If writing in a right to left script, the links look like:



    [[page-name <= label]]



But only if your text editor correctly displays right to left script.



The arrows `->` and `=>` are used interchangeably.



Previewing pages

-------------------------------------



To preview your site, run `amber server`. Alternately, there are a couple

options to preview your source files without needing to run the web server:



* Markdown preview for Chrome: https://chrome.google.com/webstore/detail/markdown-preview/jmchmkecamhbiokiopfpnfgbidieafmd

* Markdown preview for Sublime: https://github.com/revolunet/sublimetext-markdown-preview

* Markdown preview for Firefox: https://addons.mozilla.org/de/firefox/addon/markdown-viewer/  (see https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer/reviews/423328/ for rendering .md file extensions)



Setting page properties

---------------------------------



Every file can have a "properties header". It looks like this:



    @title = "A fine page"

    @toc = false



    continue on here with body text.



The properties start with '@' and are stripped out of the source file before it is rendered. Property header lines are evaluated as ruby. All properties are optional and they are inherited, including `@title`.



For haml files, the syntax is slightly different:



    - @title = "A fine page"

    - @toc = false



    %p continue on here with body text.



Available properties:



* `@title` -- The title for the page, appearing as in an H1 on the top of the page and as the HTML title. Also used for navigation title if `@nav_title` is not set. The inline H1 title does not appear unless `@title` is explicitly set for this page (i.e. the inherited value of `@title` does not trigger the automatic H1).

* `@nav_title` -- The title for the navigation to this page, as well as the HTML title if @title is not set.

* `@toc` -- If set to `false`, don't include a table of contents when rendering the file. This only applies to .rst and .md files.

* `@layout` -- Manually set the layout template to use for rendering this page.

* `@author` -- The author credit for the page.

* `@this.alias` -- Alternate paths for the page to be rendered on. May be an array. The first path will be used when linking.



To make a property none-inheritable, specify it like so: `@this.layout = 'home'`. For some properties, like `alias`, it does not make sense for the property to be inheritable.



Testing

-----------------------------------



Run all the tests:



    rake test



Run an individual test:



    ruby -b test/unit/my_test.rb



Use `-b` to show the full stack trace.



Troubleshooting

-----------------------------------



If you get an error at some point like this:



    WARNING: Nokogiri was built against LibXML version 2.8.0, but has dynamically loaded 2.9.1



It just means that libxml has been upgraded since the gem nokogiri was installed. To fix, run this:



    sudo gem pristine nokogiri