TeamStuQ Skill-Map Deployment & Usage Guide

Prerequisites

• Git (2.0+) — For cloning the repository
• Web Browser — Chrome/Firefox/Safari for viewing skill maps
• Optional: Local HTTP Server — Python 3.x or Node.js (for serving content locally with proper image loading)

Installation

Clone the repository to your local machine:

git clone https://github.com/TeamStuQ/skill-map.git
cd skill-map

Repository structure overview:

skill-map/
├── data/                          # Skill map source files
│   ├── map-MachineLearning.md     # Machine Learning skill map
│   ├── map-FrontEndEngineer.md    # Frontend development skill map
│   ├── map-BigDataEngineer.md     # Big Data skill map
│   ├── designbyStuQ/              # PNG image versions
│   │   ├── png-MachineLearning-by-StuQ.png
│   │   ├── png-FrontEnd-by-StuQ.png
│   │   └── ...
│   └── ...
├── README.md                      # Main documentation (Chinese)
└── ...

Configuration

No configuration required. This is a static documentation repository containing:

• Markdown files (.md) with skill tree structures
• PNG image files for visual skill map previews

Optional — Custom Domain Setup (for GitHub Pages): If deploying to custom domain, create CNAME file in root:

echo "your-domain.com" > CNAME

Build & Run

Local Development Server

Since the repository contains Chinese characters and image references, use a local HTTP server rather than opening files directly:

Using Python 3:

# From repository root
python -m http.server 8000
# Access at http://localhost:8000

Using Node.js (http-server):

npx http-server -p 8000
# Access at http://localhost:8000

Using PHP:

php -S localhost:8000

Viewing Content

1. Text Version: Open data/map-[Domain].md files directly in text editor or Markdown viewer
2. Image Version: Navigate to data/designbyStuQ/ and open PNG files:
   • png-MachineLearning-by-StuQ.png
   • png-FrontEnd-by-StuQ.png
   • png-BigData-by-StuQ.png
   • png-CloudComputing-by-StuQ.png
   • (And others based on domain)

Deployment

Option 1: GitHub Pages (Recommended)

Deploy directly from GitHub repository:

1. Go to repository Settings → Pages
2. Select Source: Deploy from a branch
3. Select Branch: master / (root)
4. Click Save
5. Access at https://[username].github.io/skill-map/

Enable PNG previews: Ensure data/designbyStuQ/ directory is included in deployment.

Option 2: Netlify / Vercel

Netlify Drop:

# Drag and drop the repository folder to https://app.netlify.com/drop
# Or use CLI:
netlify deploy --prod --dir=.

Vercel:

npm i -g vercel
vercel --prod

Option 3: Nginx (Self-hosted)

Create site configuration:

server {
    listen 80;
    server_name skill-map.yourdomain.com;
    root /var/www/skill-map;
    index README.md index.html;
    
    # Enable markdown rendering if using nginx markdown module
    # Or serve as static files
    
    location /data/ {
        autoindex on;  # Enable directory listing for browsing skill maps
    }
    
    # Handle Chinese characters
    charset utf-8;
}

Deploy files:

sudo cp -r skill-map /var/www/
sudo chown -R www-data:www-data /var/www/skill-map

Troubleshooting

Images Not Loading (Broken PNG links)

Issue: PNG skill maps in data/designbyStuQ/ not displaying when viewing Markdown files locally.

Solution:

• Use local HTTP server (see Build & Run section) instead of opening file:// protocol
• Check that files exist: ls data/designbyStuQ/png-*.png

Chinese Character Encoding Issues

Issue: Garbled text when viewing .md files.

Solution: Ensure UTF-8 encoding:

# Check file encoding
file -i data/map-FrontEndEngineer.md

# Convert if necessary (Linux/Mac)
iconv -f GBK -t UTF-8 data/map-XXX.md > data/map-XXX-utf8.md

Git Clone Issues (Large PNG files)

Issue: Slow clone due to binary image files.

Solution: Use shallow clone for text content only:

git clone --depth 1 https://github.com/TeamStuQ/skill-map.git

Markdown Rendering Differences

Issue: Skill tree formatting looks different on local viewer vs GitHub.

Note: These skill maps use GitHub-flavored Markdown tables and lists. For best results:

• View on GitHub directly
• Use VS Code with Markdown preview
• Use Typora or similar GFM-compatible viewer

Contribution Workflow

To contribute new skill maps:

1. Fork repository
2. Create data/map-[NewDomain].md following existing format
3. Generate PNG version (if applicable) and place in data/designbyStuQ/
4. Update main README.md table with new domain entry
5. Submit Pull Request with reference to related Issue

Contact: For major updates or corrections, email sean@geekbang.org or submit Issue at https://github.com/TeamStuQ/skill-map/issues