improving project structure

[iznaut]

instead of requiring an explicit template value, i think it makes a lot of sense to just find a template with the same name as the md file?

so assuming content/index.md and templates/index.hbs exist, index.md would currently need this to find the template:

---
template: index.hbs
---

but if they have the same name, does this value really need to be explicit? where does the global default template value fit in here? is it even helpful to have that?

[vegeta897]

This makes me think I don't really love the current folder separation of these file pairs when they're so tightly coupled.

I think it being explicit is better while this separation exists, otherwise it just feels too "magic" and I don't think people will understand what it's doing. I also think it's just kind of messy and potentially really annoying to figure out what's wrong when a pairing happens unintentionally.

[vegeta897]

I think having all the md files in content gives the wrong impression of what these files are doing or why they're separated. posts being in its own folder is great and fits the idea of "content" perfectly; it's focused entirely on stuff the user will be writing and posting to their blog. Other pages, like archive, tags, feed, not so much. The folder is acting more like it should be named "pages".

I'm thinking on the spot here so I don't have a proposal yet.

[iznaut]

yeah maybe it needs some reframing more than anything - fwiw the important part to me with the separation is that someone could reasonably create a new project using one of the starters and by only editing the markdown files, end up with a site that they could deploy and start using immediately.

ideally, ppl still get curious about how the rest of it fits together (templates, handlebars, html, etc) but if that shit is scary and you just want a blog that works i don't want to make it necessary to venture down that path just to like, change the text on the about page or whatever (but i do agree that an about blurb isn't really "content". should it live in a snippet instead?)

[iznaut]

i'm actually having a lot of thoughts about this as i'm trying to update the minimal starter lol

the current setup is causing me grief - i want to explain the /data folder here by using the fruit list example - but the templating doesn't allow me to (i need ALL my body text defined, THEN i can do template stuff)

maybe the model needs to be flipped? what if everything in /content (or whatever we call it) is treated as a snippet (no front matter processing, just gets added as a variable you can call in Handlebars (e.g. dataExplainer.md can be injected with {{ _snippets.dataExplainer }}) and anything in subfolders would work like posts or whatever do already?

[iznaut]

oh and the other part of this i guess - each template gets rendered as a page, instead of the markdown files being the definitions of "pages"? but then we'd need another folder in /templates for things that are NOT standalone pages and need to be rendered per md (like posts)?

[vegeta897]

When you said "should it live in a snippet instead" I think we thought of the same idea!

Yes, I really like the idea of content being just about text that gets consumed by the pages/templates. Page and folder structures are defined by what's in /templates. That keeps the goal of being able to edit the default site text with as little fuss as possible and also solves the awkward pairing I didn't like. People who don't care about /templates don't need to know which template is grabbing which .md.

We can think of something for the special stuff like posts but for now I wanted to express my full support.

[iznaut]

okay so the current structure is this:

• content
  • snippets
• data
• static
• templates
  • partials
• project.yaml

how about:

• content
• static
• templates
  • partials
• project.yaml
• index.hbs
• about.hbs
• (etc)

so it's more or less the same except pages are generated 1:1 with .hbs files in the root of the project. .md files in the root of /content are treated as snippets used to be (can inject wherever) and .hbs files in /templates are only used if a .md file explicitly calls for it (typically in a subfolder that might have a default set, like /posts with post.hbs

[iznaut]

oh and the implication is that /data is merged into /content, so you could have json/csv/yaml files alongside the md files and they'd all be called similarly

[iznaut]

should it also be allowed to include a .md file in the root (that has a template value) and that would also be rendered as a page (like the current model)?

but then it's weird to have posts or whatever nested in content?

[iznaut]

maybe instead of root they should go into /pages

and /content should be renamed to something more descriptive

[iznaut]

• data (md, json, yaml, csv, txt)
• pages (md and/or hbs)
• static
• templates
• project.yaml

anything in data becomes something that can be called in a Handlebars variable

[iznaut]

this also has implications for project.yaml. the current (wip) iteration looks like this:

globals:                                    # global values are available from any TemplateFile
    title: my cool blog                     # e.g. {{globals.title}} would display as "my cool blog"
    description: where i go to post
    url: cool.blog
    author:
        name: cool person
        url: https://coolperson.com/        # {{globals.author.url}} == "https://coolperson.com/"
        email: contact@coolperson.com

defaults:                                   # these are fallback values. more specific values will take priority
    title: cool untitled page
    template: default.hbs                   # every ContentFile requires a `template` value
    subfolders:
        posts:                              # values will be used for all ContentFiles in the "content/posts" folder
            title: cool untitled post       # "content/posts/my-first-post.md" has a `title` value defined, so this will not be used
            template: post.hbs              # the value of `{{{_content}}}` in this template will be replaced with the body of "content/posts/my-first-post.md"
            draft: true                     # draft content is ignored on build and won't be published

i think anything in /data would be first-class variables (e.g. if you have /data/about.md you can call that with {{ about }}). if you nested it (/data/blurbs/about.md) it would go into an object ({{ blurbs.about }})

does it make more sense to expect a /data/globals.yaml instead of having this stuff in project.yaml? or maybe globals in the project file becomes config or something to denote those values as being critical (title and url are kinda important)