Third of three parts of an introduction to my "LunaGen" software. I may add slides to this later, but currently it's just me talking. This video is also used in my unit-testing.

Transcript:

PT 3: USE

--

Now, let's take a look at the code.

--

First of all, there are FOUR separate elements that combine to make a page:

The skeleton The site data The site templates The theme.

Each of these is a tree of folders and files, which you will need to create for your site.

Then you will run LunaGen on them, to build a static HTML site to deploy.

Currently, this is all there is, but the design will eventually allow for a cron job to run on the server to update changing parts of the site, without having to fully regenerate it.

--

As a site developer using LunaGen, you create each of these four elements.

The structural division is intended to relect the different schedules for updates, as well as technical structure.

The skeleton is the base of your page. It's a directory that will be copied first into your site build. It may contain sub-folders and files.

It's also the primary way to provide images and sound or video clips that will be served directly from your site.

If your site doesn't require much of the latter, then you likely will be able to create the skeleton once, and not have to change it, unless you make a major redesign of your site.

--

The "theme" allows you to choose an external source for a lot of style decisions.

You might decide, for example, that you want several LunaGen sites to share a similar theme.

Or, you might want to use an existing theme, rather than having to do all the design work directly on your site.

The theme can also override design decisions that are included in the LunaGen source code.

These usually provide top-level functionality such as the way secondary and primary streams are combined.

Which a theme designer can alter.

A theme consists mainly of a collection of Jinja2 templates and CSS (cascading style sheets).

It may also include its own 'skeleton' folder, with additional images or other resources that the theme needs.

--

In turn, your site's "templates" folder can override the theme's templates.

This allows for theme customizations just for your site.

It's also the practical way to add complex, rich-text formatted content to a LunaGen site, as a template can contain any HTML formatting that you want.

It, too, may contain its own skeleton, which will get copied over the theme skeleton, which was copied over the original site skeleton.

It's up to you whether you want to put something in 'templates/skeleton' or just in 'skeleton'.

I would suggest that images that are solely part of the theme design should be in 'templates/skeleton' while icons, illustrations, or other things which are part of the meaning of your site should be in the main 'skeleton'.

Again, once you've chosen a theme and created a templates directory, you probably don't need to revisit those things unless you plan to make major site design changes.

--

And so that brings us to the day-to-day management part of the site, which is the 'site data' folder.

This is a file tree, consisting mainly of YAML data files.

It can also have text files, and in the future, it may be possible to include Markdown or reStructuredText files, or indeed, anything Pandoc can handle.

None of that is implemented, though, as my current application only calls for simple caption text, which can be included in the YAML.

More significantly, the folder structure can matter.

For example, the "series of episodes" functionality in LunaGen assumes that each series has a folder, with subfolders for each episode.

The YAML files in this tree also act as control files.

This is where you specify your chosen theme, for example, as well as some theme customizations, like the overall site name, contact information, and so on.

Specific data needed for LunaGen extensions can be provided in the YAML as well. As well as the necessary extra data for "series of episodes" structure (which is basically a built-in extension).

--

The idea is that you set up your site with a skeleton, a chosen theme, any overriding templates you need, and then you author the data files.

Whenever you add content, you will update the YAML data file tree, possibly adding folders or files, as needed.

Since all the style information is in the skeleton or templates, the data files you have to update regularly can be very compact.

Heavy design work isn't necessary, and consistency can largely be enforced by the templates, so you don't have to spend time on that.

Alternatively, you can change the look of the whole site by changing theme and templates.

--

I hope this introduction is useful. I may follow it up with some analysis of the code structure for developers.

Thank you for watching!