The 3Deer Portfolio Website

This repository contains the source code and content for the The 3Deer Portfolio website.

The site is a static website generated from Markdown files, providing a clean and maintainable way to manage project documentation.

How it Works

The website is built using a Python script (generate.py) that converts Markdown files into fully-styled HTML pages. This process ensures a consistent look and feel across the entire site.

The generation process involves:

1. Home Page: The main index.html is generated from INDEX.md (for content) and index_template.html (for layout and style).
2. Project Pages: For each project folder (e.g., android-model-engine), an HTML page is generated from its README.md file using the project_template.html.
3. Automatic Menus: The top navigation and in-page sidebars are automatically generated by the script, linking all pages together.

Project Structure

The repository is organized to keep content and logic separate.

.
├── android-model-engine/
│   └── README.md           # Source content for the Engine project page
├── android-model-viewer/
│   └── README.md           # Source content for the Viewer project page
├── generate.py             # The main Python script for site generation
├── INDEX.md                # Source content for the main index.html page
├── index_template.html     # Template for the main index.html page
├── project_template.html   # Template for all individual project pages
└── README.md               # This file

How to Generate the Site

To update the website or add new content, you will need to run the generation script locally.

Prerequisites

• Python 3.x
• pip (Python package installer)

1. Install Dependencies

The script requires the Markdown library. Install it using pip:

pip install Markdown

2. Run the Generator

Navigate to the root of the repository in your terminal and execute the Python script:

python generate.py

The script will automatically find all projects, process the Markdown files, and create/update the necessary .html files in the root directory.

3. Review and Commit

After running the script, you can open the generated index.html file in your browser to preview the changes. Once you are satisfied, commit and push all the updated files (.html, .md, etc.) to the main branch. GitHub Pages will automatically serve the new version of your site.

How to Add a New Project

1. Create a Project Folder: Add a new directory in the root of the repository (e.g., my-new-project/).
2. Add a README: Inside the new folder, create a README.md file and write the documentation for your project. Use Markdown headers (#, ##, etc.) to structure your content, as they will be used to generate the sidebar navigation.
3. Update the Home Page: Open INDEX.md and add a new section for your project, following the existing format:

   ## my-new-project
   
   A brief description of my awesome new project.

4. Run the Generator: Execute python generate.py to build the new HTML page and update the navigation menus.
5. Commit all the new and modified files.