HTML Course 2.4 Basic structure of a web project (folders and files)

HTML Course 2.4: Basic Structure of a Web Project (Folders and Files)

This section explains how to organize the root folder, subfolders and key files of a typical web project. Proper structure improves readability, maintainability and collaboration.

1. Root Folder

The top-level directory (often named after your project) contains the entry point index.html and configuration or documentation files. Typical contents:

index.html – main HTML file loaded by the browser
README.md – project overview and setup instructions
.gitignore – files/folders excluded from version control
package.json – (optional) Node.js dependencies and scripts

2. Assets Folder

Organize static resources (CSS, JavaScript, images, fonts) into dedicated folders. A common pattern:

css/ – stylesheets
js/ – JavaScript files
images/ (or img/) – raster and vector graphics
fonts/ – custom font files
assets/ – misc files (JSON data, icons, PDFs)

Each folder groups similar files, simplifying references in HTML and build tools.

3. Example Folder Tree

/my-web-project
  index.html           <-- Main entry point
  README.md            <-- Project overview
  .gitignore           <-- Git exclusions
  package.json         <-- Node.js setup (optional)
  /css
    style.css          <-- Base styles
    reset.css          <-- Normalize browser defaults
  /js
    main.js            <-- Application logic
    vendor.js          <-- Third-party libraries
  /images
    logo.png           <-- Company logo
    banner.jpg         <-- Hero banner
  /fonts
    opensans.woff2     <-- Web font file
  /assets
    data.json          <-- Sample data
    icons.svg          <-- SVG sprite

4. Sample `index.html` Snippet

Below is a minimal snippet showing how to reference external assets. Comments explain each part.

<!-- index.html (located in the project root) -->

<head>
  <meta charset='UTF-8'>
  <title>My Web Project</title>

  <!-- Link to reset and main stylesheet -->
  <link rel='stylesheet' href='css/reset.css'>
  <link rel='stylesheet' href='css/style.css'>
</head>

<!-- Content goes here (normally inside <body>) -->
<div id='app'>
  <header>
    <img src='images/logo.png' alt='Logo'>
    <h2>Welcome to My Site</h2>
  </header>

  <!-- Main application script -->
  <script src='js/vendor.js'></script>
  <script src='js/main.js'></script>
</div>

5. File Naming Conventions

Use lowercase letters and hyphens (kebab-case): main-header.html
Avoid spaces and special characters
Match folder names and paths exactly (case-sensitive on many servers)
Keep file extensions clear: .html, .css, .js, .png, etc.

6. Linking Strategies

Decide between relative and root-relative paths:

Relative (../css/style.css) – depends on nesting level of current file
Root-relative (/css/style.css) – always from project root (requires consistent server setup)

For single-page sites, simple relative paths are sufficient. For larger apps with routing, consider root-relative links or a build tool to rewrite paths automatically.

7. Additional Files

README.md – Instructions, dependencies, running tests
.gitignore – Ignore node_modules/, build output, IDE configs
LICENSE – Open-source license text
gulpfile.js / webpack.config.js – Build tool configuration

8. Best Practices

Keep folder depth shallow to avoid complex paths
Group files by feature or type, depending on project scale
Include a README for collaborators
Use version control (.git) and ignore build artifacts
Automate repetitive tasks (minification, linting, testing) with build tools

Adopting a clear, consistent project structure early will save time and prevent confusion as your application grows.

HTML Course 2.4 Basic structure of a web project (folders and files)