Skip to content

Latest commit

 

History

History
58 lines (37 loc) · 3.5 KB

architecture.md

File metadata and controls

58 lines (37 loc) · 3.5 KB

Architecture

This project was heavily inspired by static website generators, most notably Jekyll. Writing simple Markdown files that, at the end of a magic processing chain, turn into actual websites is very compelling for multiple reasons, but mainly the ease of content maintenance, and the low barrier of entry for people to write or modify contents without touching actual code, or without the need of a database. While this is not a static generator, in the sense that there still is a dynamic server compiling and delivering content, the content is still kept inside markdown files. The server component acts a bit like Jekyll, but instead of compiling HTML files, it just serves the results.

This allows us to have the simplicity of static page generators in terms of editing contents, but the flexibility of adding more interactive pieces as well.

Directory structure

(This is not a complete directory listing, but some of the most important directories.)

  • _server: Holds the Ruby code that turns markdown files into content to be served, and serves it.
    • assets: Holds CSS and JS files used.
    • site_modules: Hold classes for parts of contents that are more complex than a simple "take this file, render it's contents, deliver", like the blog or the install guides.
    • views: Holds layouts, as well as partials used inside mderb.
  • contents: Root for all content markdown files.
  • data: Holds yml files, to be used as a data storage for content files.
  • statics: Holds files that are deliverd as such, like blog images.
  • strings: A place for Rails-style translation yml files for reusalbe strings.
  • translations: Autogenerated from Transifex content. Basically a mirror of the contents and strings folders for each language, which overlays the English contents.

mderb

While Markdown is nice, it lacks some of the flexibility that we need for our contents. mderb is a combination of Markdown and ERB. This allows us to mix markdown content with more advanced components coded in Ruby, like using dynamic link functions:

Keep in mind that [we are here to help](<%= url_to("site", "get_help") %>) if you need us!

using variables inside Markdown content:

* `environment.certificate_authorities`: In your case, this should be `<%= @guide_data[:guide][:ca_bundle] %>`

or even use ERB logic to show/hide content based on some conditions:

<% case @guide_data[:params][:env] %>
<% when :production %>

...

<% when :development %>

...

<% end %>

Note that ERB is evaluated before markdown, so your ERB can generate markdown content.

Differences between development and production

During development, content files are served directly from the disk, allowing contributors to simply refresh the browser after changing a file. In addition to that, content sections are managed as sub-directories, instead of individual subdomains (example: blog.diaspora.software would be accessible from localhost:9292/blog/) to avoid the need of a multi-domain setup locally, which can be quite complicated. Static files from inside the statics directory will be served, and assets are compiled on-demand.

In production environments, assets have to be precompiled and static files will not be served by the runserver. In addition, all content and data files will be loaded into Redis on startup, and served from that during runtime, so we avoid slow disk IO. Link handlers will use configured subdomains instead of subdirectories for the site's sections.