Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
[enhancement] Add note on TOML table syntax to config.toml of example website #542
Part of my recent problem was that I thought TOML tables were terminated by a blank line, so inserted my permalinks table near the top of config.toml above some unrelated key/value pairs, which were consequently included in the permalinks table. Given that academic is one of the themes recommended by the blogdown package I think a reasonable proportion of new users will be equally clueless about hugo and TOML as I was.
Could you add into the config.toml of the academic example website a note along the following lines?
@rgayler Quick follow-up:
@jananiravi I know almost nothing about this. That's how i got into trouble ;-)
That's what i read in a tutorial, but it's misleading. It turns out that a name in square brackets defines a table that contains all the following key-value pairs up until the next table or the end of file. The problem I had was that I put my permalinks "somewhere near the top" but in the middle of a bunch of unrelated key-value pairs, so that the following pairs got accidentally included in my table. I believe that the safest place to add a TOML table is at the very end of the file, so there can't possibly be anything else between the new table and end of the TOML file. You need to check the TOML documentation https://github.com/toml-lang/toml#user-content-table
I believe the answer is Yes, because I can't see any other way for the system to work out which content each permalink line refers to.
As I understand it, the purpose of a slug is to give each content item a name which is fixed over time and doesn't depend on content (e.g. the title of a blog post). So you or a reader might want a link to your blog post, but you/they don't want the blog post URL to change if you edit the title of the post. There is some explanation of this here https://bookdown.org/yihui/blogdown/configuration.html#options