Hugo

Confusion about structure of Academic framework blogs

Background

I have managed to write and deploy a site using the Academic theme of Hugo, but am struggling to adapt the “widget” concept to my own site and am not sure of what paths are used as examples versus necessary for the functioning of widgets. I’m having some issues with building the site for other reasons that make learning through trial and error difficult here.

In the project root, I have the standard directories (content, config, theme, etc.). I’ve edited config/_default/menus.toml to include the url to a Blog page (/blog) and created a directory for blog-related files in the content directory (content/blog).

My confusion is regarding (a) where to place the .md files that will comprise the blog and (b) where to place the widget files to determine the layout of the blog pages.

My current understanding is that I need to place two files in content/blog: one declaring the page to be a “widget_page” and the second adding the “pages” widget to the widget page. The former looks like this:

+++
# Blog
type = "widget_page"
headless = false 
+++

The latter (take from the posts widget example found in the ExampleSite) starts with this:

+++
# A Recent Blog Posts section created with the Pages widget.
# This section displays recent blog posts from `content/post/`.

widget = "pages"  # See https://sourcethemes.com/academic/docs/page-builder/
headless = true  # This file represents a page section.
active = true  # Activate this widget? true/false
weight = 60  # Order that this section will appear.

title = "Recent Posts"
subtitle = ""

[content]
  # Page type to display. E.g. post, talk, or publication.
  page_type = "post"

Questions

  1. Supposing I have both the widget_page and pages widget files in my content/blog directory, do I need to place all of my .md blog posts in content/post or could I simply change page_type = "post" to "page_type = "foo" to pull my posts from content/foo instead?

  2. In example sites I have seen, each file in content/post contains standard front matter (e.g. that produced via R’s blogdown), but sometimes I also see an _index.md file containing the below.

    • Is this index file a post with little front-matter or does it affect the layout of other posts?
    • If I have other files in the directory, can I just delete it if the former?

---
title: Posts

# View.
#   1 = List
#   2 = Compact
#   3 = Card
view: 2

# Optional header image (relative to `static/img/` folder).
header:
  caption: ""
  image: ""
---

cc @neutreno

  1. Page Folder is a different concept to Page Type in Hugo (the underlying generator that Academic uses). So a type should be specified rather than a folder. You can then filter on a tag or category in the widget, like “foo”.

  2. _index.md is a Hugo index file - you’ll find lots of info on it in the Hugo docs and forums here.