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

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

importrefromjinja2importEnvironmentdefslugify(value): # copy of structkit/filters.pyvalue=value.lower()
value=re.sub(r'\s+', '-', value)
value=re.sub(r'[^a-z0-9-]', '', value)
returnvalueenv=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'] =slugifyprint(env.from_string('{%@ if x @%}YES{%@ endif @%}').render(x=True)) # YEStry:
env.from_string('{%@ if x %@}YES{%@ endif %@}').render(x=True)
print('BUG: %@} parsed')
exceptExceptionase:
print('%@} ->', type(e).__name__) # TemplateSyntaxErrorprint(env.from_string('{{@ n | slugify @}}').render(n="My_Project")) # myprojecttry:
env.from_string('{{@ n | slugify(separator="_") @}}').render(n="a b")
print('BUG: separator accepted')
exceptExceptionase:
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.
@httpdss
httpdss merged commit a7de87d into mainAug 20, 2026
3 checks passed
@httpdss
httpdss deleted the docs/fix-block-delimiter-and-slugify branch August 20, 2026 22:24
Sign up for freeto 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

@httpdss