colin
/
resume
1
0
Fork 1
Code Issues Pull Requests Packages Projects Releases Wiki Activity
resume/docker/resume/includes/IMPLEMENTATION_GUIDE.md

3.1 KiB
Raw Blame History

Implementation Guide: Converting to the Includes System

This guide explains how to convert the existing portfolio website to use the includes system for headers and footers.

What We've Created

  1. Header and Footer Templates

    • includes/header.html: Contains the common header elements
    • includes/footer.html: Contains the common footer elements

  2. JavaScript for Includes

    • includes.js: Handles the inclusion of header and footer files and applies the correct active states to navigation items

  3. Example Files

    • template-with-includes.html: Basic template
    • index-with-includes.html: Example of the index page
    • stories/story-with-includes.html: Example of a story page
    • one-pager-tools/tool-with-includes.html: Example of a tool page

  4. Conversion Helper

    • convert-to-includes.js: A script to help convert existing HTML files to use the includes system

Implementation Steps

1. Update the CSP in Caddyfile and Caddyfile.local

Add the includes.js script hash to the Content-Security-Policy:

Content-Security-Policy "default-src 'none'; script-src 'self' 'sha256-HASH_FOR_INCLUDES_JS' 'sha256-anTkUs/oFZJulKUMaMjZlwaALEmPOP8op0psAo5Bhh8=' 'sha256-ryQsJ+aghKKD/CeXgx8jtsnZT3Epp3EjIw8RyHIq544='; ...

2. Convert Existing Pages

For each HTML page:

  1. Add the includes.js script to the head section:

    <script src="../includes.js"></script>

    (Adjust the path as needed based on the location of the HTML file)

  2. Replace the header content (everything from the opening <body> tag to the opening <div class="container-fluid"> tag) with:

    <!-- Header Include -->
<div id="header-include"></div>

  3. Replace the footer content (everything from the closing </div> of the main container to the closing </body> tag) with:

    <!-- Footer Include -->
<div id="footer-include"></div>

You can use the convert-to-includes.js script to help with this process:

  1. Temporarily add this script to an existing page: 
    <script src="convert-to-includes.js"></script>
  2. Open the page in a browser and check the console output
  3. Use the generated HTML as a starting point for your conversion

3. Testing

After converting each page:

  1. Test the page in a browser to ensure it loads correctly
  2. Verify that the navigation active states work as expected
  3. Check that all CSS and JavaScript files are loaded correctly

Benefits

  • Easier Maintenance: Changes to the header or footer only need to be made in one place
  • Consistency: All pages will have the same header and footer structure
  • Reduced File Size: Each HTML file will be smaller since the common elements are externalized
  • Improved Developer Experience: Easier to focus on the unique content of each page

Future Enhancements

  • Dynamic Meta Tags: Enhance the includes system to support dynamic meta tags and titles
  • Page-Specific CSS/JS: Add support for page-specific CSS and JavaScript files
  • Breadcrumbs: Implement a breadcrumb system that works with the includes system