Skip to content

docs: fix block end delimiter, slugify signature, and stale repo refs - #189

Merged
httpdss merged 1 commit into
mainfrom
docs/fix-block-delimiter-and-slugify
Aug 20, 2026
Merged

docs: fix block end delimiter, slugify signature, and stale repo refs#189
httpdss merged 1 commit into
mainfrom
docs/fix-block-delimiter-and-slugify

Conversation

@httpdss

@httpdss httpdss commented Aug 20, 2026

Copy link
Copy Markdown
Owner

Three documented behaviours did not match the implementation.

  1. Block end delimiter was written as %@} in two places.
    template_renderer.py sets block_end_string='@%}'. Using %@} raises
    TemplateSyntaxError. template-variables.md contradicted itself: correct
    in the "Custom Delimiters" summary, wrong in "Block Syntax" below it.

  2. slugify was documented as taking an optional separator argument.
    filters.py defines slugify(value) with no second parameter, so
    slugify(separator="_") raises TypeError. Replaced with the actual
    behaviour and the | slugify | replace("-", "_") idiom. Also noted that
    underscores are stripped rather than converted (My_Project -> myproject).

  3. Two default_branch examples referenced httpdss/struct, the old
    repository name.

Also adds the one global missing from the reference (current_repo()),
documents to_json's indent argument, and warns that uuid() and now()
are non-deterministic — a file using either always appears in
generate --dry-run --diff, which silently ruins that diff as a drift check.

How this was verified

import re
from jinja2 import Environment

def slugify(value):                      # copy of structkit/filters.py
    value = value.lower()
    value = re.sub(r'\s+', '-', value)
    value = re.sub(r'[^a-z0-9-]', '', value)
    return value

env = Environment(
    trim_blocks=True,
    block_start_string='{%@', block_end_string='@%}',
    variable_start_string='{{@', variable_end_string='@}}',
    comment_start_string='{#@', comment_end_string='@#}',
)
env.filters['slugify'] = slugify

print(env.from_string('{%@ if x @%}YES{%@ endif @%}').render(x=True))   # YES
try:
    env.from_string('{%@ if x %@}YES{%@ endif %@}').render(x=True)
    print('BUG: %@} parsed')
except Exception as e:
    print('%@} ->', type(e).__name__)                                   # TemplateSyntaxError
print(env.from_string('{{@ n | slugify @}}').render(n="My_Project"))    # myproject
try:
    env.from_string('{{@ n | slugify(separator="_") @}}').render(n="a b")
    print('BUG: separator accepted')
except Exception as e:
    print('separator ->', type(e).__name__)                             # TypeError

Output:

YES
%@} -> TemplateSyntaxError
myproject
separator -> TypeError

Three documented behaviours did not match the implementation.

1. Block end delimiter was written as `%@}` in two places.
   template_renderer.py sets block_end_string='@%}'. Using `%@}` raises
   TemplateSyntaxError. template-variables.md contradicted itself: correct
   in the "Custom Delimiters" summary, wrong in "Block Syntax" below it.

2. `slugify` was documented as taking an optional separator argument.
   filters.py defines slugify(value) with no second parameter, so
   slugify(separator="_") raises TypeError. Replaced with the actual
   behaviour and the `| slugify | replace("-", "_")` idiom. Also noted that
   underscores are stripped rather than converted (My_Project -> myproject).

3. Two `default_branch` examples referenced `httpdss/struct`, the old
   repository name.

Also adds the one global missing from the reference (`current_repo()`),
documents `to_json`'s `indent` argument, and warns that `uuid()` and `now()`
are non-deterministic — a file using either always appears in
`generate --dry-run --diff`, which silently ruins that diff as a drift check.
@github-actions github-actions Bot added the docs label Aug 20, 2026
@httpdss
httpdss merged commit a7de87d into main Aug 20, 2026
3 checks passed
@httpdss
httpdss deleted the docs/fix-block-delimiter-and-slugify branch August 20, 2026 22:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant