Code Modules — A BBEdit-based Approach to Advanced Includes for Websites

[Christopher Werby]

Announcing the release of Code Modules — an open source project developed over years for creating and maintaining websites using BBEdit's include and variable features.

There’s documentation at https://codemodules.net/, a sample demo website at https://sample.codemodules.net/ and a GitHub repo at https://github.com/ChristopherWerby/code-modules with the source files for the sample website together with the starter files.

Just released today.  If anything strikes you as wrong or needing improvement, please let me know.  I hope you find it useful.

[Greg Raven]

Wow, what a project! I'd never thought of extending bbincludes anywhere near this far.

I won't pretend that I have anything but a cursory understanding of what you've accomplished, but here are some trivial notes so far:

• Wrap the "social media" meta information in bbignore tags so when you check site syntax you don't have multiple errors and warnings per page.
• The copyright symbol in the footer is often better as an HTML entity.
• I optimize my include files, both to cut down on transfer time and to make it easier to see where the live content is on the page. This gets around the indent issue.
• I've had terrible experiences storing my includes files inside the same folder as my project files. You seem to have finessed a way around that, but I always have separate includes and build folders in each project, so I have to be really blitzed to "update" an include file.
• There's a new version of Bootstrap 4.
• There's a new version of jQuery 3.
• This approach may be a bit daunting for beginners or those with simpler websites, but if it works as I hope it does it would get around the issue with not being able to edit BBEdit template pages and then having those changes ripple through your site, ALA Dreamweaver.

[Christopher Werby]

Hello Greg,

Thanks for taking a look!

I haven't run across a problem that required special treatment to please the validators, but the bbignore tip sounds like a good one.

On a UTF-8 website, why do you prefer the HTML entity © to ©?  I haven't seen it rendered incorrectly in years.

Optimizing the source code when built for production is a good idea. But keeping the source code readable in development is important to me.

Don't know about the problem you're referring to by mixing includes with project files.  My approach is to keep public files -- that are pushed to production -- in public/ and to keep development files that stay local in app/  Modules go in app/modules/  Seems to work.

Actually, the current version of Bootstrap is v5.  The Modern Business theme I chose for the Sample Website is just a template.  It really has nothing to do with Code Modules.  I didn't update jQuery because I didn't need it.

You're right about Code Modules being difficult for a beginner.  I wouldn't recommend it for them.  It's for intermediate/advanced BBEdit users who hand code their static websites, especially those for clients.  Making changes in a website written using Code Modules is a lot less prone to errors.

Best,

[Greg Raven]

Many years ago I had some problems with uncoded entities, so I got "stuck" encoding them. I have noticed that recent browsers seem to figure things out better, perhaps in part due to HTML5 becoming more the norm.

I understand about the different folders, but I always create a project based on the build folder, and then manually drag-n-drop the includes folder into the project. Again, it's been years since this happened, but "updating" an include file by mistake can lead to a long, painful clean-up process, so I go to great steps to avoid having it happen. If you've mastered this, no problem.

True about the latest version of Bootstrap, but some persons (such as myself) have given up on the later versions because for hand coding BS3 seems perfectly adequate. I meant, of course, that there's a later version of BS4 than the one you're calling.

I'm looking forward to digging into your code base more deeply.

[Christopher Werby]

Hi Greg,

Actually, the Modern Business template that underlies the Sample Website is using Bootstrap 5.  But I'm with you.  If it works for your project, there's little reason to upgrade.

I'm unfamiliar with your workflow.  But Git has saved my ass many many times in situations like you describe.

Best,

[Lawrence S]

I have a really dumb question, Christopher. I like this and was viewing your page source of your sample site and noticed the #bbinclude comment directives did not appear there. Maybe I'm missing something, but do you later go through a separate deployment step to scrub comments from the deployed sites? And if so, what do you use for that? I assume that part is outside the BBEdit application and your Code Modules. 

[Christopher Werby]

Hi Lawrence,

It's a really good question.

The quick answer is that the Sample Website is packaged using Parcel which does a whole lot of optimizations (like WebPack) that I only dimly understand. One of those seems to be that it strips out HTML comments. BBEdit’s Persistent Includes use the HTML comment syntax, so they get removed by Parcel's transforms. 

If you look at the source code for the built pages prior to Parcel's bundling, you'll see a single BBEdit Persistent Include on every page. The first part will be at the very top of the page and the second at the very bottom.  All of the BBEdit includes down the chain remove themselves prior to being inserted into the top level HTML page.  That removal of non-top level Includes is not something clever that I've done; that's how BBEdit built it to work.  It helps keep the source code for pages built using Code Modules clean.

https://github.com/ChristopherWerby/code-modules/blob/master/public/index.html

Thanks for looking at the project!

[Jan Erik Moström]

On 7 Sep 2021, at 23:56, Christopher Werby wrote:

> Announcing the release of Code Modules

I'm quite impressed with what you have done here. Just to make sure I've understood things correctly: this is a tool for creating web sites but not for web sites with a blog?

= jem

[David Donachie]

That probably depends how committed you are to a static/DB-less site. Long ago, before DBs were available, I had a blog that stored entries as text files, but I wouldn’t advise it now, the security risks are scary! :)

David

[Jan Erik Moström]

I'm mostly thinking of the extra work creating a blog, generating index pages etc. I mean that there are a several static site generators (usually with some kind of blogging support) like Pelican, Hugo, Nicola, Jekyll, etc, that handles that automatically. Manually maintaining a site with a fairly large number of blog entries quickly become cumbersome (if you want support for categories, tags, etc), while it's easier to maintain a site with a smaller number of pages (think documentation or a smaller info site).

Since BBEdit doesn't have support for generating various kind of indexes (that I know of), I was wondering if Code Modules have support for this. I might have missed it but I didn't see any indication of this.

= jem

[Christopher Werby]

Hi Jan,

The Sample Website for Code Modules demonstrates a simple "proto" blog with a single Blog module serving the content in a variety of ways. There's a list of recent blog posts (right sidebar), an index list of posts,  and a single page with a single post.  These all come from the Blog module serving the content in a variety of ways.

David's right - the main consideration is whether the features you wish need to be served by a database or whether a static site created at build time would work.  Features like user comments and "likes" need a database backend. But other features could probably be created using Code Modules. Not very much comes out of the box -- you'd need to write them.

Categories would probably involve adding Items to List files for each category when adding a new Blog post.  I did something similar using Code Modules to create this page — ICC Forum Guidelines.  The exemplars at the bottom of the page have a categorization feature that allows each exemplar to be placed in the exemplar sets (they look like domino pieces) scattered higher up on the page.  Each exemplar demonstrates multiple features for the guidelines, so the same exemplar is featured in multiple exemplar sets.  That's analogous to a tags/categories feature on a blog site. 

Thanks for checking out the project.

[Christopher Werby]

Hi David,

A static pre-built site -- just a bunch of files -- on a properly configured server has to be far more secure than a production server hosting a real-time db and building pages on the fly.  Code Modules creates HTML pages at build time. The pages are completely static when they hit the server.  It's like comparing some Netlify site to WordPress.

Are you imagining a different approach where the text files are included at call time on the server? That could certainly be problematic.

[Jan Erik Moström]

On 15 Sep 2021, at 18:24, Christopher Werby wrote:

> The Sample Website for Code Modules demonstrates a simple "proto" blog with a single Blog module serving the content in a variety of ways. There's a list of recent blog posts (right sidebar), an index list of posts, and a single page with a single post. These all come from the Blog module serving the content in a variety of ways.

I missed that part, I need to take a closer look at this.

> David's right - the main consideration is whether the features you wish need to be served by a database or whether a static site created at build time would work.

There is no need for a database, support for tags/categories can be handled by most static generators

> Features like user comments and "likes" need a database backend. But other features could probably be created using Code Modules. Not very much comes out of the box -- you'd need to write them.

I don't care about comments/likes etc.

> Categories would probably involve adding Items to List files for each category when adding a new Blog post. I did something similar using Code Modules to create this page — ICC Forum Guidelines. The exemplars at the bottom of the page have a categorization feature that allows each exemplar to be placed in the exemplar sets (they look like domino pieces) scattered higher up on the page. Each exemplar demonstrates multiple features for the guidelines, so the same exemplar is featured in multiple exemplar sets. That's analogous to a tags/categories feature on a blog site.

Thanks, I check this out.

= jem