Skip to content

🚀 Getting Started - Complete Guide

What You Have

A fully functional documentation website for the B.Tech Electrical & Electronics Engineering program at SRMIST with: - ✅ All course information from the official SRMIST website - ✅ Professional Material Design theme - ✅ 5 comprehensive pages of content - ✅ Responsive design (mobile, tablet, desktop) - ✅ Dark/light mode toggle - ✅ Search functionality - ✅ Ready for deployment

📋 Files Overview

your-project/
├── docs/                      # Your content files
│   ├── index.md              # Home page
│   ├── eligibility.md        # Eligibility criteria
│   ├── admission.md          # Admission process
│   ├── curriculum.md         # Full curriculum (8 semesters)
│   ├── contact.md            # Contact & facilities
│   ├── stylesheets/
│   │   └── extra.css         # Custom styling
│   ├── javascripts/
│   │   └── extra.js          # Interactive features
│   └── assets/               # Images (add your logo here)
│
├── .github/
│   └── workflows/
│       └── deploy.yml        # Auto-deployment to GitHub Pages
│
├── mkdocs.yml                # Site configuration
├── requirements.txt          # Python dependencies
├── .gitignore               # Git ignore rules
├── README.md                 # Project documentation
├── QUICKSTART.md            # Quick start guide
└── PROJECT_SUMMARY.md       # What's included

🎯 Three Ways to Use This

Option 1: View Locally (Testing) ⚡

Best for: Testing before deploying, making changes

Time: 2 minutes

Steps: 1. Open Terminal/Command Prompt 2. Navigate to this folder: bash cd path/to/your-project 3. Install dependencies: bash pip install -r requirements.txt 4. Start the server: bash mkdocs serve 5. Open browser: http://127.0.0.1:8000

Benefits: - See changes instantly - No internet needed - Perfect for development

Best for: Sharing with others, permanent website

Time: 5 minutes

Cost: FREE

Result: Live website at https://yourusername.github.io/your-repo/

Step-by-Step:

A. Create GitHub Account (if you don't have one) - Go to github.com - Sign up for free

B. Create New Repository 1. Click the "+" icon → "New repository" 2. Repository name: srm-eee-docs (or any name) 3. Description: "B.Tech EEE Program Documentation" 4. Choose: Public 5. Don't check any boxes (no README, .gitignore, or license) 6. Click "Create repository"

C. Upload Your Files

Option C1: Using Git (Command Line) ```bash # Navigate to your project folder cd path/to/your-project

# Initialize git git init git add . git commit -m "Initial commit: EEE documentation site"

# Add remote (replace YOUR-USERNAME and YOUR-REPO) git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPO.git

# Push to GitHub git branch -M main git push -u origin main ```

Option C2: Using GitHub Website (Easier!) 1. In your new repository, click "uploading an existing file" 2. Drag and drop ALL your files 3. Scroll down and click "Commit changes"

D. Enable GitHub Pages 1. Go to your repository on GitHub 2. Click "Settings" (top menu) 3. Click "Pages" (left sidebar) 4. Under "Build and deployment": - Source: GitHub Actions 5. Wait 2-3 minutes

E. View Your Live Site! - Your site URL: https://YOUR-USERNAME.github.io/YOUR-REPO/ - Example: https://john123.github.io/srm-eee-docs/

Automatic Updates: - Every time you push changes to GitHub, the site automatically rebuilds! - No manual deployment needed

Option 3: Export Static Files 📦

Best for: Uploading to your own hosting, USB drives, sharing offline

Steps:

cd path/to/your-project
pip install -r requirements.txt
mkdocs build

The site/ folder now contains your complete website: - Upload to any web hosting - Share the folder - Open site/index.html in any browser

🎨 Customization Guide

Change Site Name

Edit mkdocs.yml:

site_name: Your Custom Name Here
site_description: Your description

Change Colors

Edit docs/stylesheets/extra.css:

:root {
  --srm-blue: #1565C0;    /* Main color */
  --srm-orange: #FF6F00;   /* Accent color */
}
  1. Save your logo as logo.png (PNG format, 200x200px recommended)
  2. Put it in docs/assets/ folder
  3. Logo will automatically appear in the header!

Update Content

Simply edit the .md files in the docs/ folder: - Home page: docs/index.md - Eligibility: docs/eligibility.md - Admission: docs/admission.md - Curriculum: docs/curriculum.md - Contact: docs/contact.md

Markdown is easy! Examples:

# Big Heading
## Medium Heading
### Small Heading

**bold text**
*italic text*

- Bullet point 1
- Bullet point 2

[Link text](https://example.com)

![Image](path/to/image.png)

Add New Page

  1. Create new file: docs/your-page.md
  2. Add to mkdocs.yml under nav:: ```yaml nav:
    • Home: index.md
    • Your New Page: your-page.md
    • Eligibility: eligibility.md # ... rest of pages ```

🔧 Troubleshooting

"pip: command not found"

Install Python from python.org

"mkdocs: command not found"

pip install mkdocs mkdocs-material
# or
pip3 install -r requirements.txt

Port 8000 in use

mkdocs serve -a 127.0.0.1:8001

GitHub Pages not working

  • Wait 2-3 minutes after first push
  • Check Settings → Pages is configured correctly
  • Check Actions tab for deployment status
  • Make sure repository is Public

Changes not showing on GitHub Pages

  • Wait 1-2 minutes for rebuild
  • Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
  • Clear browser cache

Build errors

# Clean build
mkdocs build --clean

# Verbose mode to see errors
mkdocs build --verbose

📚 Learn More

Documentation

Video Tutorials

  • Search YouTube for "MkDocs tutorial"
  • "GitHub Pages tutorial"

✅ Quick Checklist

Before deploying, make sure: - [ ] Tested locally with mkdocs serve - [ ] All content is correct - [ ] Links work properly - [ ] Images load correctly - [ ] Checked on mobile device - [ ] Updated site name in mkdocs.yml - [ ] Added your logo (optional)

🎉 Success Indicators

Locally Working When:

  • ✅ mkdocs serve runs without errors
  • ✅ Browser shows site at localhost:8000
  • ✅ Navigation works
  • ✅ Search works

GitHub Pages Working When:

  • ✅ Repository has your files
  • ✅ Actions tab shows successful deployment
  • ✅ Settings → Pages shows your site URL
  • ✅ Visiting URL shows your site

💡 Pro Tips

  1. Test Locally First: Always test changes with mkdocs serve before pushing to GitHub

  2. Regular Backups: Keep a copy of your files in multiple places

  3. Small Commits: Make small, frequent commits to GitHub rather than big ones

  4. Use Branches: For major changes, create a new branch: bash git checkout -b new-feature # make changes git commit -m "Added new feature" git push origin new-feature

  5. Document Changes: Write clear commit messages explaining what you changed

  6. Mobile Testing: Always check how it looks on mobile devices

  7. Performance: Keep images small (compress them before adding)

  8. Analytics: Add Google Analytics code to track visitors (optional)

🆘 Need More Help?

  1. Read the README.md for detailed project info
  2. Check QUICKSTART.md for quick commands
  3. See PROJECT_SUMMARY.md for what's included
  4. Google specific errors (they're usually simple fixes!)
  5. Ask in GitHub Issues if you create a public repo

🚀 Next Steps

  1. Right Now: Test locally bash pip install -r requirements.txt mkdocs serve

  2. In 5 Minutes: Deploy to GitHub Pages

  3. Create repo
  4. Upload files

  5. Enable Pages

  6. Later: Customize

  7. Change colors
  8. Add logo

  9. Update content

  10. Share: Send your URL to others!

You're all set! Everything is ready to go. Just follow one of the three options above and you'll have a live website in minutes! 🎊

Good luck! 🌟