Create a blog theme

[matthew-carroll]

Blogs are the most common use-case for static site generators.

Create a blog theme for Static Shock that makes it quick and easy for a new Static Shock user to create, compose, and deploy a blog.

[suragch]

This is the use-case I'm looking for. I have a bunch of websites that I'd like to theme with Static Shock. They're not blogs, per se, but a series of lessons or tutorials on a common theme. I can't use the docs template because the topics don't have a link to a Dart package that I'm documenting. Here are three as examples:

• StudyMongolian.net: A series of Mongolian language lessons.
• aePronunciation.com: A series of American English pronunciation lessons.
• LearnDart.dev: Tutorials about Flutter and Dart.

If the template created something similar to the Static Shock site itself, that would be great: a home page with a menu that links to a series of Markdown pages.

If I were to work on building this template, what all would be involved? Could you create a list of subtasks?

[matthew-carroll]

@suragch Let's start by agreeing on a set of features that such a template should provide. Can you propose an initial list here? Then we can iterate on that.

[suragch]

@matthew-carroll

Here are the types of sites that might benefit from a template:

• Dart package documentation (already exists)
• Flutter app landing page with accompanying documentation
• Blog
• Tutorials/lessons

The last three could probably be combined into one, but they do have some feature differences.

These features are common to all of them:

• CSS theming that covers
  • padding,
  • quotes,
  • inline code,
  • code blocks,
  • background and text colors,
  • and header size.
• responsive layout for both desktop and mobile.
• top menu on wide screens that becomes a hamburger menu on mobile.
• social media tags (#138)
• side menu for navigating to related articles (or sections within the current article).
• homepage (not markdown, maybe an image and a call to action button?).
• "This website was built with Static Shock" footer.
• one or two example markdown pages.

These features would be specific to the template type:

Flutter app site

• Landing page with an app screenshot and button links to the Android and iOS app stores
• Privacy policy page
• Terms of service page
• App tutorial docs (optional)
• About/contact page

Blog

• RSS feed
• Tags (?)
• Browse by date (?)

Tutorials

• Code blocks with a copy button
• Article table of contents

[matthew-carroll]

Let's focus this ticket on the blog use-case. If the others end up working with the same approach, then great, but best to solve a specific problem first.

It looks like most of the bullets are aimed at layout and styling. I'm wondering how including those details would work out in reality. For example, you mentioned porting 3 of your websites. Don't your websites have an existing layout with existing styles and pages and navigation that you'll want to replicate? If so, how do you see yourself making use of CSS classes, a pre-built layout, and a navigation menu that come with the template?

[suragch]

@matthew-carroll Sure, focusing on the blog use-case is fine.

Yes, the three websites that I plan to port will certainly have different styling. The layout may or may not be different. What a blog template would be useful for is to provide some useful defaults. Even without much of a web dev backgound, I can probably edit these defaults into something that matches the style of my site. Without a template, on the other hand, I get something like the current state of learndart.dev. It's much harder to start from zero and work up to a site like Static Shock.

[matthew-carroll]

Perhaps we can discover these needs in realtime. Would you like to select one of your websites that you want to port and we can identify specific hurdles that you hit and solve them as you hit them?

Whichever site that is, let's pause the moment you hit a difficulty and figure out what we can provide in a template to solve that.

[suragch]

That sounds good. I'll choose aepronunciation.com.

If I understand your meaning, this is how I would start:

mkdir aepronunciation
cd aepronunciation
shock template blog

At that point, we hit the first breaking point since blog doesn't exist yet.

Or is your meaning that I should create the site with shock create and then build from there?

[matthew-carroll]

For now, begin with shock create. To go through this exercise we'll probably have you re-generate this project many times so that we can run through the initial tooling evaluation.

So starting with shock create, let me know the first problem you run into, and we'll take it from there.

[suragch]

I've created a new project:

mkdir aepronunciation
cd aepronunciation
shock create

I'm presented with a source/index.md Markdown file as the home page. My first problem is that I would like the homepage to be HTML or Jaspr, not Markdown. Most of the site will be Markdown, but not the home page. I wouldn't expect the default to be exactly what I need, but if there were some sort of scaffold, that would be good. A logo image, a menu bar, a little text, and a call to action button.

[matthew-carroll]

Thanks for the use-case. Let's see what we can do.

First, the technical way to get what you want is to simply rename that file to index.html and then put HTML in it.

Obviously, the point of your comment is that you'd rather not do that.

I see three options:

• Change the template so that index is HTML instead of Markdown
• Add a template parameter to choose between HTML and Markdown
• Add an entirely new template that gives you an index.html instead of index.md

What do you think?

[suragch]

I'd go with the first option: change the template so that index is HTML.

For every site I can think of making (and it seems that your sites follow this pattern), the home page isn't Markdown. If that's not what people want, it's easy enough to delete the HTML and replace it with an index.md page. It's more difficult to go the other direction (Markdown to HTML). At this point, it's not even clear to me how a Markdown home page could contain a menu.

[matthew-carroll]

I created a blog template in this PR: https://github.com/Flutter-Bounty-Hunters/static_shock/pull/158

It looks terrible and doesn't do a whole lot, but we can iterate on that template.

[suragch]

It took me a little while to learn how to get the new updates. pub.dev says the current version is 0.0.11 but when I ran shock version it said 0.0.8. I finally realized that the latest changes were included in this version.

I ran the following command:

shock template blog --project-name aepronunciation --blog-title "American English Pronunciation"

I got log message about the following error:

Failed to build your static site. Please check your project for errors. Error code: 254

However, the project continued to build without any noticeable problems.

Observations

This is already a big advance toward the default layout that would be useful for anyone starting out with a new blog site. I like the default margin support for screen width resizing. I also like that the home page is HTML rather than markdown. And I like how the images for a particular post are stored in the post folder rather than in the central images folder.

Next iteration

For aepronunciation I'll need some static pages that are accessible from a menu. I don't know how well this fits into the blog theme, though I suppose even a blog might have some static pages like an about me or a contact page.

[matthew-carroll]

Failed to build your static site. Please check your project for errors. Error code: 254

That initial error message has typically indicated that something in the generated project wasn't right. During development if I screwed up any of the template variables and the code didn't compile or something like that, I'd get a failure after initial project creation.

If you ever find out more about why that's happening, please let me know.

For aepronunciation I'll need some static pages that are accessible from a menu.

Do you have a wireframe for that?

[suragch]

I could try to draw up a wireframe for what I think a blog homepage might look like, but if you want to accelerate development, what I really need isn't a blog site. I can take a blog template and make it work by throwing out all the parts I don't need, but it's a little harder for me to imagine what a good blog homepage might look like when I'm not actually building a blog.

What I'm trying to build for all of my static sites are topical sites with a collection of articles. The homepage summarizes and promotes the content topic of the site and the menu directs readers to the topical articles. I would have a much easier time designing a generic wireframe for that kind of thing. I can create a new issue for that if that works better. Or if you just used a slightly simplified and generic version of the Static Shock homepage itself, that's what I'm looking for.

Here is something quick, but I can make it better if you need me to. The green are parts to keep. The red are parts that can be simplified away. (Instead of the "Activate Static Shock" section, you could have a couple sentences of descriptive text.)

[matthew-carroll]

@suragch you mentioned that you're not technically trying to create blogs, and you used a documentation website as the closest thing to what you're trying to create. Can you let me know what it is you're actually trying to build? Maybe pick one website and let me know what unique needs it has, specifically?

[suragch]

Here is a desktop view of what I'd like to make for aepronunciation.com:

And here is a mobile view:

The hamburger menu would contain the items App, Lessons, Contact.