Add clarity to docs on permalinks placeholders and builtins

[EmilyGraceSeville7cf]

Summary

• Describe :output_ext as a placeholder
• Add note on W prefix to :week when using weekdate builtin

Context

Questions

What to do with date and pretty formats now? I want fix documentation errors because it's hard to write JSON schema when they are exist.

[EmilyGraceSeville7cf]

This is my attempt to write regex for:

• global permalink: ^((/(:(year|short_year|month|i_month|short_month|long_month|day|i_day|y_day|w_year|week|w_day|short_day|long_day|hour|minute|second|title|slug|categories|slugified_categories))+)+|date|pretty|ordinal|weekdate|none)$
• collection permalink: ^(/(:(collection|path|name|title|output_ext))+)+$

[mattr-]

looks good to me

[mattr-]

I went to go double check the code and now I'm confused. The documentation mirrors the code exactly. When you use these permalink styles on a site, are you seeing different results?

It's my review

[EmilyGraceSeville7cf]

1. There is an example: permalink: /:categories/:year/:month/:day/:title:output_ext. But in this placeholder list no output_ext is listed.

2. Here is an example: /:categories/:year/W:week/:short_day/:title:output_ext but my regex can't catch W: and rejects this value. What is W:? I found no information about is.

🤔

[ashmaroli]

Blocking this since docs should mirror Ruby codebase.

[ashmaroli]

• There is an example: permalink: /:categories/:year/:month/:day/:title:output_ext. But in this placeholder list no output_ext is listed.

Agreed. But it is mentioned under subsequent section towards end of page
Perhaps this pull request may add the missing placeholder to the global table..

• Here is an example: /:categories/:year/W:week/:short_day/:title:output_ext but my regex can't catch W: and rejects this value. What is W:? I found no information about is.

W will act as a prefix to placeholder :week.
For example, W10..

Agreed that it has not been documented anywhere. Perhaps this pull request could add that info..

[EmilyGraceSeville7cf]

W will act as a prefix to placeholder :week.

What placeholder prefixes are allowed?

[ashmaroli]

What placeholder prefixes are allowed?

@EmilySeville7cfg See underlying code for reference:

jekyll/lib/jekyll/configuration.rb

Lines 272 to 278 in 19868d5

	STYLE_TO_PERMALINK = {
	:none => "/:categories/:title:output_ext",
	:date => "/:categories/:year/:month/:day/:title:output_ext",
	:ordinal => "/:categories/:year/:y_day/:title:output_ext",
	:pretty => "/:categories/:year/:month/:day/:title/",
	:weekdate => "/:categories/:year/W:week/:short_day/:title:output_ext",
	}.freeze

Built-ins are syntactic-sugars (or shorthands) to a particular implementation.
So, weekdate is a shorthand to a particular template: /:categories/:year/W:week/:short_day/:title:output_ext, i.e. no other prefix supported. If one does not want that W, they'll have to manually write the template without the W.

---

P.S. You may add a note to reduce confusion.. Also, please update the PR title and description to better describe latest diff.

Concerns addressed

[ashmaroli]

Thanks @EmilySeville7cfg
@jekyllbot: merge +doc