# `Literature.StaticPages.Generator`

Defines a static page generator for a given publication.
Provides a set of functions to automate the generation of static pages such as index,
paginated index, tags, authors, and show pages(see `Available Pages`).
It supports customization through options like pagination size, output path, and custom templates.
Static pages are stored in the `static_pages_storage_dir` Literature config.

## Functions
  * `generate_all/2` - Generates all specified static pages for the publication.
  * `generate/2` - Generates a specific static page type for the publication, given the page type options.
  * `generate/3` - Generates a specific post, author or tag show page, given the resource slug.
  * `store_path/2` - Returns the output directory for the generated files inside `priv/static`.
  * `generate_file/4` - Writes rendered static page to memory or to a file inside `store_path`.

## Options for `generate/2` and `generate_all/2`
  * `:publication_slug` (required) - The slug of the publication for which to generate pages.
  * `:base_url` (required) - URL used inside the pages for links, pagination, and SEO tags.
  * `:page_size` - Number of posts per page for paginated pages (default: `10`).
  * `:path` - Base path for generated static files (default: `"/"`).
  * `:templates` - a module providing `Phoenix.Component` for each page listed in `Available Pages`
                   e.g. `index/1`, `index_page/1`, etc. (default: `Literature.StaticPages.Templates`).
                   See the `Literature.StaticPages.Templates` module for Behaviour and example.
  * `write_to` - Specifies where to write the generated files. Can be `:memory`(default) or `:file`. Returns `Phoenix.HTML.Safe.t()` when writing to memory.

## Available Pages

The following page types can be generated by this module:

  * `:index`        - Main index page for posts with no pagination. (e.g., `/en/blog/index.html`).
  * `:index_page`   - Paginated index pages for posts (e.g., `/en/blog/page/<page_number>/index.html`).
  * `:show_post`    - Show page for specific post. (e.g., `/en/blog/<post.slug>/index.html`).
  * `:tags`         - Index page for tags. (e.g., `/en/blog/tags/index.html`)
  * `:show_tag`     - Show page for a specific tag (e.g., `/en/blog/tags/<tag.slug>.html`).
  * `:show_tag_page` - Paginated show pages for a specific tag (e.g., `/en/blog/tags/<tag.slug>/page/<page_number>/index.html`).
  * `:authors`      - Index page for authors. (e.g., `/en/blog/authors/index.html`)
  * `:show_author`  - Show page for a specific author (e.g., `/en/blog/authors/<author.slug>.html`).
  * `:show_author_page` - Paginated show pages for a specific author (e.g., `/en/blog/authors/<author.slug>/page/<page_number>/index.html`).

## Usage

    alias Literature.StaticPages.Generator

    @opts [
      page_size: 10,
      path: "/en",
      publication_slug: "blog",
      templates: Literature.StaticPages.Templates,
      base_url: "https://example.com"
    ]

    def generate_blog_pages(pubication_slug) do
      Generator.generate(:index, @opts)
      Generator.generate(:show_post, @opts)
      Generator.generate(:authors, @opts)
      Generator.generate(:show_author_page, @opts)
      Generator.generate(:tags, @opts)
      Generator.generate(:show_tag_page, @opts)
      ...

    end

    def generate_all do
      Generator.generate_all([:index_page, :authors, :show_author_page, :tags, :show_tag_page], @opts)
    end

# `page_type`

```elixir
@type page_type() ::
  :index
  | :index_page
  | :show_post
  | :authors
  | :show_author
  | :show_author_page
  | :tags
  | :show_tag
  | :show_tag_page
```

# `write_to`

```elixir
@type write_to() :: :file | :memory
```

# `generate`

```elixir
@spec generate(
  page_type :: page_type(),
  keyword()
) :: :ok | {:ok, list()}
```

# `generate`

```elixir
@spec generate(:show_post | :show_tag | :show_author, String.t(), keyword()) ::
  :ok | {:ok, list()}
```

# `generate_all`

```elixir
@spec generate_all(
  [page_type()],
  keyword()
) :: :ok | {:ok, list()}
```

# `generate_file`

```elixir
@spec generate_file(String.t(), String.t(), Phoenix.HTML.Safe.t(), write_to()) ::
  :ok | {:ok, tuple()} | {:error, term()}
```

Writes rendered HTML content to a file within the given static output directory.

# `store_path`

```elixir
@spec store_path(String.t()) :: String.t()
```

Returns the output directory for static files.

---

*Consult [api-reference.md](api-reference.md) for complete listing*