![[Creative Commons BY-NC-SA 3.0 Unported License]](http://www.obdurodon.org/images/cc/88x31.png "Creative Commons BY-NC-SA 3.0 Unported License")
Last modified:
2022-12-31T18:18:50+0000
Maintained by: David J. Birnbaum (djbpitt@gmail.com)
Last modified:
2022-12-31T18:18:50+0000
This tutorial is designed to guide you in creating a directory structure of your project site and in choosing clear, robust, and maintainable file names. The basic principle is that everything about your project, including your directory structure and file names, should be as clear and self-documenting as possible. Not only will this make it easier for all members of the project team to understand the structure and content of the site, but it will help you if you return to the project months or years from now, when you can no longer remember the decisions you made or the reasons behind them.
It’s easy to fall into a pattern of dumping all of your project files into your main project directory, since that’s the location that requires the least thought. If you have just a few files that may not be a problem, but otherwise your site quickly becomes chaotic. The details may vary from project to project, and your project mentor will assist you in assessing your individual needs, but the basic structure we recommend for projects is that the main project directory should contain only your HTML pages, and other files should be installed in the following subdirectories:
Some of these directories, especially those for data and images, may themselves contain subdirectories that help you group your data in a natural way.
Directory and file names should observe most of the same conventions as file names for homework assignments, such as:
Filenames must not contain any characters except letters, digits, hyphens, underscores, and periods. Most importantly, no space characters or punctuation other than hyphens, underscores, and periods should be used in file names.
Filenames must have appropriate extensions: .xml, .css, .xsl, .js, .xhtml, .svg, etc. Note that although .html is a common extension for HTML files, there are some configuration peculiarities on Obdurodon that require .xhtml. If you use .html, it will probably work anyway, but it may not.
Your file name capitalization has to be consistent. In particular, image files (including some you may download from other sites) might have .jpg or .JPG, or .png or .PNG, extensions. Convert all of those to lower-case only.
2015,
2015-09-28(yyyy-mm-dd; month and day must be two digits, left padded with a zero if necessary, with month before day). Gory details: https://en.wikipedia.org/wiki/ISO_8601. The rationale for this format is that ISO 8601 dates sort naturally in chronological order.
Have a consistent filenaming convention. For example, if your XML documents are personal letters, you might use date_senderSurname_recipientSurname_number.xml, e.g., 2015-09-28_obama_biden_02.xml (second letter from Obama to Biden on September 28, 2015). The exact filename components and their exact order isn’t the most important thing; what’s most important is that you use the same convention consistently throughout your project.
Document your directory structure and your naming conventions unless they are truly self-evident. You can use a plain text (e.g., readme.txt) or markdown file (e.g., readme.md), and put it in the main project directory. You don’t have to link to it because it isn’t for site visitors; it’s there so that future developers (including your future self, should you return to your project after a hiatus and no longer remember your conventions) will be able to make sense of the site. This is called process metadata, that is, metadata about the processes you followed to create your site.
Image files should normally be webp, jpg, or png and no larger than required for your project. Full-screen images should be no more than 1600 pixels on the long axis. If you don’t already have a favorite image editor, you can convert large images to more appropriate smaller ones on the command line with ImageMagick or, if you prefer a graphic image tool, with Irfanview (Windows) or GIMP (Mac, Linux), both of which are freely available.
If you aren’t comfortable letting your visitors’ browsers use their default fonts, you should specify a font stack. If you use uncommon characters that may not be supported by the fonts on the average user’s system, you can provide web fonts.