Design Proposal: defaultDate & defaultTitle

[vassudanagunta]

I changed my mind. I now like @maxandersen's improvement (#3762) of @devjack's implementation (#3310) of @xaprb's now nearly 4 year old request (#285). A single config value. A simple bool that enables "smart" date detection (that could get smarter over time), rather than asking the user to figure out a regex:

 defaultLayout                        string
 useModTimeAsFallback                 bool  <--- existing, by #2239
 useFilenameDateAsFallback            bool  <--- proposed by #3762
 useFilenameOrHeadingAsTitleFallback  bool  <--- implied by #3805 
 defaultContentLanguage               string
 defaultContentLanguageInSubdir       bool

concerns

• All the other settings that control defaults are prefixed with "default". These two (three) aren't.
• What if useModTimeAsFallback and useFilenameDateAsFallback are both set to TRUE?
• Do we always extract it (so it is not part of slug) or will some people want it to remain? What if I have dates in all my filenames, but in some cases have the date in the front matter? The result will be some slugs will have dates and others won't. Is the solution then to add another config item, keepDateInSlug? Hmmm.
• What if it should be PublishDate, not Date that comes from the filename?

an alternate solution

This proposal address #285, #3805 and #4340 and all of the concerns above. Compare the set of settings above to this:

defaultLayout                  string
defaultDate                    string  <--- for #285
defaultTitle                   string  <--- for #3805
defaultContentLanguage         string
defaultContentLanguageInSubdir bool

defaultDate

defaultDate has the following symbolic values (final identifiers may be different):

• none
• in filename        same as Better more complete fix for allowing filename to set date and slug #3762
• remove from filename    same as in filename, but removes date from slug
• file mod time        same as useModTimeAsFallback, which we can deprecate
• file creation time    future, if needed

In the future we can also distinguish between Date and PublishDate if necessary:

defaultDate="file mod time"
defaultPublishDate="in filename"

We can also use this setting to address #4340, replacing the currently hardcoded logic for defaulting Date, PubDate and LastMod to each other (which I think is problematic). We simply add a couple more symbolic values for the setting:

defaultDate="publish date"
defaultPublishDate="date"

In the future we can also add precedence logic:

defaultDate="in filename, file creation time, publish date"

defaultTitle

We can give defaultTitle similar options:

• none
• filename      full filename
• in filename     filename less parts we've parsed for anything else, e.g. defaultDate
• heading      use the top level heading (H1) in the content as title

we can do this incrementally

We don't have to support all of the setting values I show above immediately, or ever. But having the single string settings that accepts values from a documented enumeration of values is both simple and flexible. And if we really, really need to, we could one day allow it to be set to a regular expression.

[bep]

Here are my thoughts on config flags:

• If the sensible default behaviour fits > 90% of the use cases, we don't add one (unless it has some bad side-effects for the minority with no workaround)
• We never add config options if it makes the content less portable (so: index.md, _index.md and any other name standard for content filenames is set in stone)
• We set the default to what is best for the majority
• We use enableSomething if the default is false, else disableSomething

We're not adding any publishDate options unless you can argue the first bullet point above. And we already have too many flags/options. Looking at your arguments above, the need for a new naming standard (a flag slice of sorts) comes from proposed new flags in unmerged PRs, which would have to be evaluated against the "rule set" above.

In my head we have:

• useModTimeAsFallback (existing)
• And probably the new useFilenameDateAsFallback

No more. And they have an implied and sensible order:

For date:

1. date in front matter
2. In filename if useFilenameDateAsFallback
3. In file on disk if useModTimeAsFallback is set

For publishDate:

1. publishDate in front matter
2. From date

There will always be some people wanting really special things. But flexibility comes at a cost. Note that if implementing this as a "slice of something" internally makes it simpler, fine, but we're not adding a "config date matrix" unless it is needed and/or makes this significantly simpler to understand/configure.

[vassudanagunta]

As I explained in another comment, my real goal is simply for Hugo to properly support content without front matter. So I'd be completely happy with:

For date:

1. date in front matter
2. In filename

For title:

1. title in front matter
2. in content top level heading (e.g. Markdown # title ) [1]
3. In filename [2]

Whether this happens by default or by configuration switches, I don't care. I proposed the above as a way to keep everyone happy, as well as set Hugo up for new behavior without creating boolean config switch hell.

The advantage of symbolic switches is that you can have a single config property for an item, and introduce new options simply by adding new legal values. You keep the door open for supporting other things even if unlikely, e.g. customized precedence order, arbitrary regular expressions, whatever. It's just a matter of supporting a new legal value. It is just an idea. Perhaps a bad one.

Before we make any decisions on config switches, I think we should decide whether Hugo will support #285, #3805 and #4359. Will Hugo will support content without front matter? Should I start a forum topic?

---

[1] This is important because so much Markown content already exists with a title, right there in the content at the top as a heading. Why force authors to add it again in front matter, and have to keep them in sync when they change the title?

[2] The case where both date and title are in the filename must be considered.

[kaushalmodi]

in content top level heading (e.g. Markdown # title )[1]

FWIW, this would be great! I am OCD (and also that's invalid HTML) about not having multiple <h1> headers on the same page. So if # title is not used, it comes natural to folks to do # heading 1!

At the moment, I ensure that there are no level-1 Markdown headings in my posts, because Blackfriday will render all those headings as h1, including the title. So why not just use level-1 Markdown for what it's supposed to.

[reinier]

Any progress on this yet? I would love to use Hugo without any front matter as it makes importing my markdown files a lot easier and it is more true to the nature of easy publishing markdown files.

[vassudanagunta]

@bep implemented the date part of my proposal in #4436. My earlier PR to extract title from filename (#4359) was not accepted.

true to the nature of easy publishing markdown files

Exactly!!! This is something I'm working on, both as a standard and a Hugo implementation of the standard. Feel free to check it out (you'll have to build it for yourself for now). At the moment it does this:

• Title from first level one heading or filename.
• Pure Markdown internal links, unix-style path semantics. e.g. all of the following will resolve exactly as you would expect them too:

  [file in same directory](article.md)
  [file in child directory](subsection/sub-article.md)
  [file in parent directory](../super-article.md)
  [file via absolute path from content root](/section/article.md)
  

  Many markdown editors as well as GitHub's repo web interface support navigating such links in the source. In other words you can both read and navigate your Markdown without having to publish, in line with Markdown's original intent.
  Of course Hugo will correctly transform the links appropriately on publish (e.g. to the html versions).
• Alternate home and index filenames, including README.md. Combined with the navigable source links, your content folder is fully functional as-is on GitHub web repo interface.

Additional features forthcoming... And hopefully I'll be ready to publish the standard proposal soon.

[rdwatters]

Title from first level one heading or filename.

Seems handy, and I agree that there should be only 1 <h1> per page until browsers start using the document outline model (if that ever happens).

[file in same directory](article.md)
[file in child directory](subsection/sub-article.md)
[file in parent directory](../super-article.md)
[file via absolute path from content root](/section/article.md)

What about CommonMark and keeping it true to the spec (if you believe there is such a thing) @vassudanagunta ?

[vassudanagunta]

@rdwatters,

What about CommonMark and keeping it true to the spec (if you believe there is such a thing) @vassudanagunta ?

Absolutely! I'm an active participant of the CommonMark community and am "all-in" with regard to CommonMark. Maybe you misunderstand? Markaround doesn't change the Markdown spec (whichever flavor you use). It specifies how you assembly a collection of Markdown files together (e.g. Hugo's content folder). In fact, it is in some ways an "un-specification", in that it says you can organize your pure-Markdown content within a root folder any way you wish, and a Markaround compliant tool (editor, SSG, etc) has to be able to handle it as-is.

The link examples above are pure Markdown, and are already supported by many tools and GitHub. If, for example, the Hugo Docs used links like the above (rather than proprietary ref/relref shortcodes), you could browse and navigate the doc source directly on GitHub, and edit the files with Typora which supports Markdown source link navigation. The goal is intuitive simplicity and portability across tools.

I'd love to hear your thoughts.

[rdwatters]

Thanks for the great intel, @vassudanagunta . I see your point now 😄 That said, I don't want to get this thread too off track, which I am often wont to do. Also, thanks much for the inadvertent intro to Typora. That app is beautiful.

[vassudanagunta]

Thanks for the kind words, @rdwatters. 😄 We'll pick up this tangent later, after I push out a draft fo the Markaround spec. I'd love to get your feedback. Send me an email if you're open to me running questions or ideas by you as I flesh it out.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.