[Shock] - Support componentized file structure

matthew-carroll commented 3 months ago

Static Shock currently supports pipeline access to layouts and components. Those are currently defined a specific location.

For example:

/source/
  _includes/
    components/
    layouts/

Similarly, the Sass plugin compiles Sass to CSS, again from a specific location:

/source/
  styles/

Images also tend to be stored in a global location:

/source/
  images/

That said, image are found with Pickers, which offer more control than the layout and component hard-coded locations.

These locations might be configurable, but they're always just one location. This concept of a global location leads to global references, which can work against natural packaging.

Templates and styles beside the content

Consider a website that has a bunch of guides, all of which use the same template and styles. It might be desirable to create a directory for the content, template, and styles, as shown below:

/source/
  guides/
    _data.yaml
    guide.jinja
    guide.sass
    my-guide-1.md
    my-guide-2/
      index.md
      screenshot-1.png
      screenshot-2.png
    my-guide-3.md

In this example, there's no good reason to force guide.jinja into /source/_includes/layouts/ and there's no reason to force guide.sass into /source/styles/.

Holistic Components

A layout or component likely includes HTML and CSS. It may even include JS. It would be nice to be able to define such a component across multiple files:

/source/
  _includes/
    components/
      footer.html
      google-analytics.html
      navbar.jinja
      table-of-contents/
        component.html
        styles.sass
        scripts.js
    layouts/
      top-level-page/
        layout.html
        styles.sass
        scripts.js

Challenges

To support arbitrary layout and component locations, we'd need to figure out at least the following issues:

How to tell the difference between a layout/component vs a piece of content/asset
How to coordinate the CSS that's produced by Sass with the code that needs the CSS
How to coordinate the final location of a JS script with the thing that consumes it

Ideas

We could introduce an extension for layouts and components: my-layout.jinja.layout and my-component.jinja.component.

When looking specifically within /source/_includes/components/ and /source/_includes/layouts/ we could look specifically for a file called component.xxxx and layout.xxxx, respectively. The layout is probably always Jinja at this point. But the component could be .html, .jinja, .txt, or anything else.

suragch commented 1 month ago

I'm writing an article that has several screen shots. I'd like to keep the images close to the article source text. The following structure would be nice:

source/
    posts/
        my-post-one/
            img/
                image1.png
                image2.png
            my-post-one.md
        my-post-two/
            img/
                image1.png
                image2.png
            my-post-two.md

From within the article text, I would reference the images like so:

![My Image](./img/image1.png)
![My Image](./img/image2.png)

The two posts would be available at:

example.com/posts/my-post-one/
example.com/posts/my-post-two/

Is this currently possible or is this what this issue is addressing?

After further investigation...

I see now that I need to add a new picker in main.dart:

..pick(DirectoryPicker.parse("images"))
..pick(DirectoryPicker.parse("posts/my-post-one/img")) // new line

Now it works:

Ideally, I would prefer not to have to add a new picker for every article I write. But I guess a picker is already better than my current strategy, which has been to replicate the article file structure within the images folder.

Also, is there something specific about the Docusaurus images that you wanted me to see?

Docusaurus allows relative links to images within the article working directory (as SS also does I now understand) but without adding additional configuration elsewhere.