From 6b6cf201a8c991f6027149d09caed663768d6d8f Mon Sep 17 00:00:00 2001 From: skierpage Date: Mon, 1 Jul 2024 18:51:53 -0700 Subject: [PATCH] docs: Add Site generation reference documentation Explain at a high level what `cobalt serve` and `cobalt build` do. Based on this, suggest how to run Cobalt in an existing site's directory. Add the new page to the Reference documentation navigation. Mention the new page on the Start (getting-started) page. Fixes #95 --- _layouts/docs.liquid | 1 + docs/site-gen.md | 70 ++++++++++++++++++++++++++++++++++++++++++++ getting-started.md | 5 +++- 3 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 docs/site-gen.md diff --git a/_layouts/docs.liquid b/_layouts/docs.liquid index 0196e77..383f9bf 100644 --- a/_layouts/docs.liquid +++ b/_layouts/docs.liquid @@ -16,6 +16,7 @@
  • Install
  • Usage
  • Directory Structure
    • +
  • Site generation
  • Configuration
    • diff --git a/docs/site-gen.md b/docs/site-gen.md new file mode 100644 index 0000000..0c7407c --- /dev/null +++ b/docs/site-gen.md @@ -0,0 +1,70 @@ +--- +title: "Docs::Site generation" +layout: docs.liquid +data: + route: site-gen +--- +## Site generation + +[`cobalt serve`](/docs/usage) and `cobalt build` process the entire source directory the same +way. They write assets, transformed files, and generated pages to an output +directory; `cobalt serve` writes to a temporary directory while `cobalt build` +writes to a [`destination`](/docs/config) directory (default `./_site`). `cobalt serve` also +runs a web server to serve this static content, and then continues to watch the +source directory for changes. + +### Generation process + +The generation process is, approximately, +1. Cobalt considers every file in the [`source`](/docs/config)directory. +2. It skips directories and file names beginning with dot `.` or underscore + `_`, and other files and directories. You can specify additional files and + directories to skip using the [`ignore`](/docs/config) configuration + variable. +3. It treats all remaining files that aren't pages and posts (see later) as + [assets](/docs/assets) and copies them to the output directory. It may + preprocess Sass files to turn them into CSS. +4. If a file has an extension in [`template_extensions`](/docs/config) (the + default extensions are `.html` and `.md`), then Cobalt treats it as a + [page](/docs/pages): + - Cobalt looks for a [frontmatter](/docs/front) section (lines between a pair + of `---`) in it, if any, and evaluates metadata settings in it. + - If the site [configuration](/docs/configuration) or the page's + frontmatter specifies a [layout](/docs/layout), Cobalt wraps the file in + that layout's Liquid template. + - Cobalt evaluates any [liquid template](https://shopify.github.io/liquid/) + expressions in the file (to simplify, directives inside curly braces `{...}`). + - Cobalt writes the transformed file to the output directory with, by + default, a `.html` extension. A file with no frontmatter or liquid + template expressions will be unchanged. +5. If a file with a template extension is in the [`posts`](/docs/posts) + directory, Cobalt processes it further, such as draft handling. A page's + frontmatter can direct Cobalt to generate a list of pages, for example a + paginated list of blog posts. +6. Cobalt may generates additional files, such as an `rss.xml` feed. + +### Generating from an existing static site + +You can run `cobalt serve` or `cobalt build` in your existing static site's +directory. +- They will create a lot of files in the output directory, but will not create + new files or modify existing files in your source directory. _Caution_, + `cobalt build` will overwrite files in an existing destination directory + (which defaults to `./_site`). +- The commands will complain if you don't have a `_config.yml` file or specify + the path to one, nevertheless Cobalt will do default processing. +- Even if your existng files have extensions that Cobalt treats as pages, as + explained in "Generation process" they will not be transformed if they don't + contain liquid templates and a frontmatter section, and you don't specify a + default [`layout`](/docs/config). +- Some assets that you want to appear in the output directory, such as + `.htaccess` files and the `.well-known` directory, may not appear; + conversely, unintended files may appear. + +To start adjusting Cobalt's site generation you need to provide a +[configuration](/docs/config) file. Running [`cobalt init`](docs/usage/) will +create a `_config.yml` file and a few sample files and layout. If files +already exist with the same names, `cobalt init` will not overwrite them but +fail, so you could run it in your existing site directory, or you can run it +in an empty directory and copy over files as needed. You can specify the path +to your configuration file with the `--config` _\_ command-line option. diff --git a/getting-started.md b/getting-started.md index 993ce17..d548111 100644 --- a/getting-started.md +++ b/getting-started.md @@ -13,7 +13,7 @@ or $ curl -LSfs https://raw.githubusercontent.com/crate-ci/gh-install/master/v1/install.sh | sh -s -- --git cobalt-org/cobalt.rs --crate cobalt ``` -### Usage +### Basic usage #### Start @@ -68,3 +68,6 @@ $ cobalt build ``` The site is sitting in `_site` and ready to be uploaded! + +If you have an existing site, read [Site generation](/docs/site-gen) to better +understand Cobalt's operation so you can run it in your site directory.