From a2f172764bc558e44def177cf0520e8b4590b565 Mon Sep 17 00:00:00 2001 From: Jay Miller Date: Wed, 18 Mar 2026 22:11:58 -0400 Subject: [PATCH] add docs from render-engine --- docs/README.md | 1 + docs/cli.md | 230 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 231 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/cli.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..6d07c78 --- /dev/null +++ b/docs/README.md @@ -0,0 +1 @@ +The docs at cli.md are loaded into the render-engine docs using mkdocs-multirepo plugin. Do not build/serve the docs directly here diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..a52d883 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,230 @@ +--- +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 + +```toml +[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. + +```bash +render-engine init [TEMPLATE] [OPTIONS] +``` + +**Arguments:** + +- `TEMPLATE`: Template URL or path (default: ) + +**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:** + +```bash +# 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. + +```bash +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:** + +```bash +# 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. + +```bash +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:** + +```bash +# 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. + +```bash +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:** + +```bash +# 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.). + +```bash +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:** + +```bash +# 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