New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[enhancement] Add note on TOML table syntax to config.toml of example website #542

Closed
rgayler opened this Issue May 18, 2018 · 3 comments

Comments

Projects
None yet
3 participants
@rgayler

rgayler commented May 18, 2018

Hi George,

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?

# A line consisting of a name in square brackets defines a table which will contain all the following
# key/value pairs until the next table definition or the end of file. For more detail on the TOML syntax
# see https://github.com/toml-lang/toml
#
# For example:
# [permalinks]
#   post = "/:slug"
#   talk = "/presentation/:slug"
#
#   publication = "/pub/:slug"
#   project = "/proj/:slug"
# [anothertable]
#   key1 = "value1"
@jananiravi

This comment has been minimized.

jananiravi commented May 21, 2018

@rgayler Quick follow-up:

  • Do these [permalinks] lines have to correspond with the way the publication, project, talk folders are named in content/?
  • How and when should I define these 'slugs'?
  • And when you say add to the top of the file, is it right after file definition? Should the precise location matter to its working?
    I'm new to toml and hugo. thanks for your help!
@rgayler

This comment has been minimized.

rgayler commented May 22, 2018

@jananiravi I know almost nothing about this. That's how i got into trouble ;-)

add to the top of the file

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

Do these [permalinks] lines have to correspond with the way the publication, project, talk folders are named in content/?

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.

How and when should I define these 'slugs'?

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

@gcushen

This comment has been minimized.

Owner

gcushen commented Jun 3, 2018

Thanks for the feedback @rgayler ! I'll consider highlighting how TOML works either in config and/or on the documentation website.

@gcushen gcushen added this to the v2.3 milestone Jun 3, 2018

@gcushen gcushen closed this in 2abaa84 Jul 7, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment