Feedback after first use

[suragch]

I used Static Shock for the first time today. I like it and it was relatively painless to set up.

Here is some feedback that I hope will be helpful as you continue development:

Creating a new project

The use of shock create was a little unexpected. Most command line tools (including flutter, dart, jaspr) include the project name after the create keyword. Even though the docs say exactly what to do, I didn't believe the docs and still tried to add my project name like so:

shock create my_project

The error message quickly let me know that I couldn't add a project name like that, so then I did it the right way.

My second surprise was that all of the project files were created in my current folder. I was expecting them to be created in a new folder. That makes a bit of a mess to clean up if I have other files in the current folder.

Recommendation

At the minimum, I would change your documentation to something like this:

mkdir my_project
cd my_project
shock create

But my preference would be to require adding the project name like so:

shock create my_project

Updating the default markdown page

After running shock serve and seeing the default page, I wanted to update the style/layout. Specifically, I wanted to increase the padding. Since the frontmatter referenced layouts/homepage.jinja, I expected to see a layouts folder in or near the root of the project. I didn't find any there, but after searching for a while, found it buried in _includes.

I don't know much HTML or CSS and even less Jinja, so once I found homepage.jinja, I was at a bit of a loss for what to do with it. I checked the documentation to see if there were any directions on how to add padding or somehow convert the default page to something that looks more like a Markdown-based blog post, but I couldn't find anything specific. Finally I gave homepage.jinja to an AI chat and asked it to help me add the padding. It gave me the following to add to the header:

<style>
  main {
    padding-left: 100px;
    padding-right: 100px;
  }
</style>

That works and puts the page in an acceptable format to be able to present some content in a meeting tomorrow.

Recommendation

• I would make the HTML/Jinja styling for the default page include padding that a blog article might use.
• Or, include a short tutorial about how to style/layout a page with Jinja.
• And, include a link to some third-party resources that teach how to use Jinja.
• Or, ideally, don't require users to know anything about Jinja or HTML for standard use cases. (I know that probably isn't possible without a ton of dev work, but my ideal static site generator would generate content just from markdown and would be customizable just with Dart code--no HTML, no CSS, no Jinja. To be clear, I'm not expecting that; that's just what my dream static site generator would be like.)

Thank you for your work on this. I'm looking forward to migrating some websites to use SS in the future.

[matthew-carroll]

Thanks for giving Static Shock a try. I'll aim to work in some of the suggestions before the next release.

Based on your use of Jaspr, do you think there's a good way to use Jaspr to help people create website layouts that bypass the HTML and CSS you ran into?

[suragch]

Jaspr is more approachable for me than plain HTML and CSS. A Jaspr plugin in SS or an SS plugin in Jaspr might be a good solution.

[matthew-carroll]

What kind of files would you expect to find if Jaspr were used? Would there just be a bunch of Dart files?

[suragch]

Let me think about this for a day or two. I'm trying to imagine what it would look like.

[suragch]

As I study the index.jinja source for the staticshock.io home page, it appears that Jinja is an alternative to Jaspr. If Static Shock were to use Jaspr instead of Jinja, then I would expect there to be a Dart Jaspr file everywhere that SS uses a Jinja file. I also see in your Jinja file there are references to components. I didn't find the location of those components but they seem to have a similar semantic meaning to Jaspr components.

I'm not certain that you should use Jaspr instead of Jinja since Jinja is probably much more mature. However, from what I see, the learning curve looks a little steep on Jinja. Your website looks great, but unless there were a great Jinja tutorial, I wouldn't be able to make anything like it. This might be a high barrier for new user adoption since most interested people will be Dart developers and not necessarily web developers.

[matthew-carroll]

Jinja is an injection template syntax. It's essentially equivalent in purpose to Mustache, Handlebars, Nunjucks, etc. There are many of those.

Jinja has no understanding of the browser DOM, or HTML, or CSS, or anything else. It's just a way of saying that something like {{ myVar }} should be replaced with the value of myVar when the website is built.

Therefore, I'd be surprised if Jaspr and Jinja were solving the same problems.

As for layouts and components - those are two groups of things that were introduced in Static Shock. They aren't a part of Jinja.

In a Static Shock website we expect to find template layout files under source/_includes/layouts and component templates under source/_includes/components. Those layouts and components probably use Jinja because they'll need to inject variables during build time. But the concept of layouts and components is a Static Shock thing.

[suragch]

I see. That does make Jinja itself much simpler. My understanding now is that the .jinja files are essentially HTML files with injected variables using the {{ myVar }} syntax. However, that just moves the complexity to the HTML. To develop a good looking site, I need to lay it out and style it with HTML and CSS. Am I correct in that understanding?

[matthew-carroll]

My understanding now is that the .jinja files are essentially HTML files with injected variables using the {{ myVar }} syntax.

That's correct. Though it's worth pointing out that technically Jinja syntax could appear anywhere. For example, you can also inject Jinja variables into Markdown content, before the Markdown gets converted into HTML.

To develop a good looking site, I need to lay it out and style it with HTML and CSS. Am I correct in that understanding?

Yes, this is true for all websites, including ones that use Jaspr. HTML and CSS are all that browsers understand (except for the new technology of canvas painting).

However, to regularly produce website content without regularly dealing with HTML and CSS, we support Markdown to write pages that automatically plug into HTML layouts when you publish. Included in the Markdown support is a syntax called Frontmatter - this is a way of declaring properties at the top of your page file, which can then be used by the Jinja templates. For example, you'll notice that Static Shock Markdown pages have a "title" property defined at the very top. You can put any properties you want in there.

For CSS, we have a slightly more convenient tool which is Sass. Sass is CSS plus a number of more convenient syntaxes. Sass compiles down to traditional CSS in the final build.

[suragch]

So as Static Shock is currently implemented, users would need to write the HTML layout and CSS (or Sass) styling from scratch once and then could use that as a template for their Markdown pages. It would be nice to have a few pre-made templates included with Static Shock. Then if someone wanted a different layout or style they could just tweak the template.

[matthew-carroll]

We'll have some templates. Here's a documentation website template I just merged: https://github.com/Flutter-Bounty-Hunters/static_shock/pull/112

A blog template will come next.

[suragch]

That's great! I think that's the missing piece I was looking for. You could also invite users to submit templates that you could link to or host. That would take some work off of you and develop a sense of community around Static Shock.