Project structure

A YASSB project in it's simplest form is just HTML pages. Plain and simple.

More complex sites can be composed, alongside with HTML files, also with many more file formats, including MarkDown and JSON. Additionally, custom directives and custom renderers can be used to automatically generate and populate your files.

A typical YASSB project is organized in different folders. The following structure is encouraged, but all folder/file names can be personalised in the configuration:

Custom project structure

You can change the project structure and the folder names in the configuration.

At run time, all folders are resolved relative to the folder of which they are a child of in the predefined project structure. For example, the folder components is resolved relative to the folder ./src/app.

So if you rename in the configuration the components folder to something else, for example fragments, the final folder will be resolved to ./src/app/fragments.

Example:

// config/default.js

module.exports {
  workingDir: {
    components: 'fragments'
  }
}

// result ./src/app/fragments

Because folders are resolved as relative paths, you can alter the structure of the project when setting custom folder names. For example, if you want the fragments folder to be a child of the ./src folder, instead of the ./src/app folder, you can do the following:

// config/default.js

module.exports {
  workingDir: {
    components: '../fragments'
  }
}

// result ./src/fragments

In this way you can even reference folders that are outside of the root folder of the project, for example by passing ../../../../shared-code/components.

This can be very handy to reuse the same folder in multiple projects (for example the components folder), or to store your source files (MarkDown, JSON, etc.) anywhere on your disk.

How web pages are generated

The starting point for building a website with YASSB is to add a index.html file in pages.

Because YASSB works with HTML files, any page you put in your pages is already a valid HTML file that you can serve statically from any web server.

Each html file in this folder will become a page on your website. In this folder you should put the index file of your website (index.html), and any other individual page you might want to have on your website (e.g. about.html, contact.html, products/awesome-thing.html, etc.).

To reuse the same HTML code across multiple pages, you can put HTML snippets in dedicated HTML files in components (e.g. header.component.html). These are injected into pages at compilation time by the component directive.

If you have lists of things, instead of manually typing them, you can generate the lists with the create-from-data-source directive. The data source JSON files must placed in the folder data-sources. Custom renderes (JS/TS/JSX/TSX functions) can be provided to generate any kind of list/layout.

If you have some text that you'd like to write in MarkDown (e.g. blog posts), you'll place the template for the pages to be generated in pages-to-generate. For each .md file provided (from anywhere on your disk), the generate-from-files directive will create a new HTML file with the content of the .md file processed as html.

Because generating files might create a lot of fles, you will probably want to create custom indexes. To do so, you will only need to add to any HTML file the public-file-list directive to specify the path for which you want to create a list of file found at such path. Custom renderes (JS/TS/JSX/TSX functions) can be provided to generate any kind of layout.