Skip to content

cli.md

Latest commit

 

History

History
230 lines (158 loc) · 5.75 KB

cli.md

File metadata and controls

230 lines (158 loc) · 5.75 KB
title Render Engine CLI
description Guide to using Render Engine CLI for creating, building, and serving your site.
date August 22, 2024
tags
render-engine
cli
site-setup
build
serve

Render Engine comes with a CLI that can be used to create, build, and serve your site.

!!! Note The CLI is no longer a part of the Render Engine package and must be installed separately. To install run pip install render-engine-cli. Render Engine can be installed together with the CLI as well using pip install render-engine[cli].

pyproject.toml Configuration

The Render Engine CLI can be configured through your pyproject.toml file to set default values and avoid repetitive command-line arguments.

Configuration Options

  • module: The Python module containing your Site class
  • site: The name of your Site class within the module
  • collection: Default collection name for the new-entry command

Example Configuration

[tool.render-engine.cli]
module = "my_site"
site = "MySite"
collection = "posts"

With this configuration, commands that normally require module:site can be run without arguments:

  • render-engine build instead of render-engine build my_site:MySite
  • render-engine serve instead of render-engine serve my_site:MySite

CLI Commands

init

Create a new Render Engine site from a template.

render-engine init [TEMPLATE] [OPTIONS]

Arguments:

Options:

  • --extra-context, -e: Extra context as JSON string
  • --no-input: Skip all prompts
  • --output-dir: Output directory (default: ./)
  • --config-file, -c: Path to cookiecutter config file

Examples:

# Use default template
render-engine init

# Use custom template with no prompts
render-engine init https://github.com/myuser/mytemplate --no-input

# Provide extra context
render-engine init --extra-context '{"project_name": "My Blog"}'

build

Build your static site.

render-engine build [MODULE:SITE] [OPTIONS]

Arguments:

  • MODULE:SITE: Module path and site class (e.g., my_site:MySite)

Options:

  • --clean, -c: Remove output folder before building

Examples:

# Basic build
render-engine build my_site:MySite

# Build with clean
render-engine build my_site:MySite --clean

# Using config defaults
render-engine build

serve

Serve your site locally with auto-reload capability.

render-engine serve [MODULE:SITE] [OPTIONS]

Arguments:

  • MODULE:SITE: Module path and site class

Options:

  • --clean, -c: Clean output folder before building
  • --reload, -r: Auto-reload on file changes
  • --directory, -d: Directory to serve (default: output)
  • --port, -p: Port number (default: 8000)

Examples:

# Basic serve
render-engine serve my_site:MySite

# Serve with auto-reload on port 3000
render-engine serve my_site:MySite --reload --port 3000

# Clean build and serve
render-engine serve my_site:MySite --clean --reload

templates

List available templates from installed themes.

render-engine templates [MODULE:SITE] [OPTIONS]

Arguments:

  • MODULE:SITE: Module path and site class

Options:

  • --theme-name: Specific theme to list templates from
  • --filter-value: Filter templates by name

Examples:

# List all templates
render-engine templates my_site:MySite

# List templates from specific theme
render-engine templates my_site:MySite --theme-name bootstrap

# Filter templates containing "post"
render-engine templates my_site:MySite --filter-value post

new-entry

Create a new collection entry (blog post, page, etc.).

render-engine new-entry [MODULE:SITE] [COLLECTION] [FILENAME] [OPTIONS]

Arguments:

  • MODULE:SITE: Module path and site class
  • COLLECTION: Collection name (e.g., "blog", "pages")
  • FILENAME: Output filename for the new entry

Options:

  • --content: Content string for the entry
  • --content-file: Path to file containing content
  • --title: Entry title
  • --slug: URL slug for the entry
  • --args: Additional metadata as key=value or key:value pairs
  • --include-date: Add today's date to the entry. NOTE: If this is set and a date is included in the --args the one from the --args will be used.

Examples:

# Create a basic blog post
render-engine new-entry my_site:MySite blog my-first-post.md --title "My First Post"

# Create post with content
render-engine new-entry my_site:MySite blog hello.md --content "Hello, world!" --title "Hello"

# Create post from file with metadata
render-engine new-entry my_site:MySite blog review.md \
    --content-file draft.txt \
    --title "Product Review" \
    --args author="John Doe" \
    --args category=reviews \
    --args tags="product,tech"

# Using slug
render-engine new-entry my_site:MySite pages about.md \
    --title "About Us" \
    --slug "about-us"

# With --include-date
render-engine new-entry my_site:MySite pages about.md \
    --include-date

Notes:

  • The --args option can be used multiple times
  • Arguments can use either = or : as separator
  • If EDITOR environment variable is set, the file opens automatically after creation
  • Cannot use both --content and --content-file options

Usage Tips

  1. Configuration First: Set up your pyproject.toml to avoid typing module:site repeatedly
  2. Development Workflow: Use serve --reload during development for instant feedback
  3. Clean Builds: Use --clean flag when switching between major changes
  4. Template Discovery: Use templates --filter-value to find specific template types
  5. Batch Entry Creation: Combine new-entry with shell scripts for bulk content creation