Project organization

BBEdit gives you tremendous flexibility in setting up your project and workflow. The scheme that works for me after building hundreds of websites boils down to a master folder that holds three subfolders and the .bbprojectd file. A skeletonized version of the master folder for this website looks like this:

├── bbedit-guide-build
│   ├── _assets
│   ├── _redirects
│   ├── .editorconfig
│   ├── 00-introduction
│   ├── 01-getting-started
│   ├── 02-projects
│   │   ├── index.html
│   │   ├── organization.html
│   ├── 03-conversions
│   ├── 04-frameworks
│   ├── 05-helpers
│   ├── 06-advanced
│   ├── 07-help
│   ├── 404.html
│   ├── config.codekit3
│   ├── humans.txt
│   ├── index.html
│   ├── robots.txt
│   ├── sitemap.txt
│   └── sitemap.xml
├── bbedit-guide-includes
│   ├── footer.incl
│   ├── guide.tmpl
│   ├── header.incl
│   ├── meta.incl
│   ├── nav.incl
│   └── siteicons.incl
├── bbedit-guide-source
│   └── cgi-bin
│       ├── bbedit_config.xml
│       ├── sitemap_gen.py
│       └── sitemap_gen.sh
└── bbedit-guide.bbprojectd

You can assign any names you want to your folders. This is the naming pattern that works for me.

The Build folder

The build folder (in this case, bbedit-guide-build) is where all the files go that make up the website. BBEdit also refers to this as the local site folder in Site Settings …. This is also the folder that I recommend committing if you use a git repository (such as Github, Gitlab, etc.), rather than the master folder. Depending on your build process, there may be other files (including a .git folder to hold the git repository files), but this should give you an idea what the local site folder looks like. This webpage is organization.html, which as you can see is inside the 02-projects folder, which is inside the bbedit-guide-build folder, which is inside the bbedit-guide folder.

Note that I keep most of my assets — audio files, CSS files, images, JavaScript files, site icons, videos, etc. — inside a folder called _assets. Depending on your build process, this may be a bad name because some of the new Static Site Generators (SSGs) apply special handling to folders that start with an underscore. I have been using this naming convention since before SSGs became a thing, and because I used BBEdit instead of what they now call a SSG, there is no problem with this name. The main reason I do this is because BBEdit sorts this file to the top of the Project sidebar, so I don’t have to go hunting for it.

A couple of other notes: The _redirects file is specific to Netlify, which hosts this site. If this site were on a traditional server, that would be a .htaccess file. The .editorconfig file contains certain settings for BBEdit so that each of my projects looks the same when I work on it. Finally, the config.codekit file is for preview and pre-processing the site through CodeKit as I work. Each of these files is optional, as is the humans.txt file. The robots.txt and sitemap files are technically optional, but highly recommended.

Remember, do not store your BBEdit persistent include or template files inside your local site root folder. If you do, BBEdit will update them, too, when it updates the rest of your site. Although it is not obvious from the code example above, each of these include files is in a templates and includes folder outside of the local site root folder, where BBEdit has been told to look for them in the Project Settings.

The Includes folder

This is where I store my include and template files. Include files have the .incl filename extension. Template files have the .tmpl filename extension.

The siteicons.incl file contains meta content that could be put into the meta.incl file, but then it BBEdit would include it in every HTML file on the site. For reasons unknown, some of the meta directives for site icons are not valid HTML, so if the code was on every page, BBEdit would flag errors on every page in the website. This is technically correct behavior but having that many normal errors makes it difficult to spot the errors you’re trying to eliminate. Hence, a separate include file for the site icons, which is included only on the main index.html file.

The Source folder

Virtually every project I have ever worked on has other materials that don’t go on the site, but are too valuable to toss out. The source folder allows me to keep track of those assets. This listing shows a cgi-bin folder, which is where I keep the files needed to (re-)build the sitemap.xml file as needed. If this site was hosted on a traditional server, I could have this in the build folder and run it either locally or on the remote server, but the JAMStack server that hosts this site does not execute either Python or bash files, so there is no point in having them in the build folder.

The BBprojectd folder

It may not look like it, but bbedit-guide.bbprojectd is actually a special type of folder containing files that help BBEdit keep track of various site-related information. Typically, you would never open this as a folder. When you double-click it, BBEdit opens your project with all of your settings.