mkdocs

Solutions Architect Public Cloud Documentation

Personal documentation site for Solutions Architecture and Public Cloud technologies, built with MkDocs and deployed to GitHub Pages.

🌐 Live Site

Visit the documentation site at: https://elfizazi.github.io/mkdocs/

📚 What’s Included

• Cloud Platforms: Comprehensive guides for AWS, Azure, and GCP
• Architecture Patterns: Best practices and design patterns
• Best Practices: Industry-standard approaches to cloud solutions
• Resources: Curated learning materials and references

🚀 Local Development

Prerequisites

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

Setup

1. Clone the repository:

   git clone https://github.com/elfizazi/mkdocs.git
   cd mkdocs
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Serve the documentation locally:

   mkdocs serve
   

4. Open your browser and navigate to http://127.0.0.1:8000/

Building the Site

To build the static site:

mkdocs build

The built site will be in the site/ directory.

🔧 GitHub Pages Deployment

Initial Setup (One-time)

This repository is configured to automatically deploy to GitHub Pages using GitHub Actions.

Important: For private repositories, you need to enable GitHub Pages:

1. Go to your repository settings
2. Navigate to Pages (under “Code and automation”)
3. Under Build and deployment:
   • Source: Select GitHub Actions
4. The site will be available at https://elfizazi.github.io/mkdocs/

Automatic Deployment

Every push to the main or master branch will automatically:

1. Build the MkDocs site
2. Deploy to GitHub Pages

You can also manually trigger the deployment:

1. Go to the Actions tab in your repository
2. Select the “Deploy MkDocs to GitHub Pages” workflow
3. Click “Run workflow”

📝 Adding Content

File Structure

mkdocs/
├── docs/
│   ├── index.md              # Home page
│   ├── architecture/         # Architecture documentation
│   ├── cloud/                # Cloud platform guides
│   ├── best-practices.md     # Best practices
│   └── resources.md          # Learning resources
├── mkdocs.yml                # MkDocs configuration
└── requirements.txt          # Python dependencies

Adding New Pages

1. Create a new markdown file in the docs/ directory
2. Add the page to the navigation in mkdocs.yml: ```yaml nav:
   • Home: index.md
   • Your New Page: your-page.md ```

🎨 Customization

The site uses the Material for MkDocs theme. You can customize:

• Theme colors: Edit the theme.palette section in mkdocs.yml
• Navigation: Modify the nav section in mkdocs.yml
• Features: Enable/disable features in theme.features

📄 License

This documentation is for personal use as a Solutions Architect knowledge base.

🤝 Contributing

This is a personal documentation repository. If you have suggestions or find errors, feel free to open an issue.

---

Built with MkDocs and Material for MkDocs