INS IT Guide

Bilingual (English/French) IT documentation for Institut de Neurosciences des Systèmes (INS).

Live site: https://ins-amu.github.io/it-guide

Overview

This documentation provides comprehensive IT information for INS members, including:

• Getting started with AMU accounts
• Network connectivity (Ethernet, WiFi, VPN)
• Communication tools (Email, Framateam)
• Storage solutions (AMUBox)
• Software licenses and installation
• Hardware and equipment
• IT purchasing via MATINFO
• Computing resources (HPC cluster)
• System administration

Technology Stack

• MkDocs - Static site generator
• Material for MkDocs - Theme
• mkdocs-static-i18n - Bilingual support
• mkdocs-with-pdf - PDF export
• Local Gemma 4 server - Translation assistance

Quick Start

1. Setup

# Clone the repository
git clone https://github.com/ins-amu/it-guide.git
cd it-guide

# Run setup script (creates venv and installs dependencies)
./setup.sh

2. Local Development

# Serve the site locally (with live reload)
./serve.sh

# The site will be available at: http://127.0.0.1:8000

3. Build

# Build HTML only
./build.sh

# Build HTML + PDF
./build-pdf.sh

The generated site will be in the site/ directory.

Directory Structure

it-guide/
├── docs/                      # Documentation source files
│   ├── index.md               # Home page (English)
│   ├── index.fr.md            # Home page (French)
│   ├── getting-started/       # Getting started guides
│   ├── network/               # Network documentation
│   ├── communication/         # Communication tools
│   ├── storage/               # Storage solutions
│   ├── software/              # Software guides
│   ├── hardware/              # Hardware information
│   ├── purchasing/            # Procurement procedures
│   ├── computing/             # HPC resources
│   ├── admin/                 # Administration guides
│   └── reference/             # Reference materials
├── refs/                      # Source materials (not in build)
│   └── 2024-guide.md          # Original guide
├── scripts/                   # Utility scripts
│   └── translate.py           # Gemma-powered translation automation
├── mkdocs.yml                 # MkDocs configuration
├── requirements.txt           # Python dependencies
├── setup.sh                   # Setup script
├── serve.sh                   # Development server
├── build.sh                   # Build HTML
└── build-pdf.sh               # Build HTML + PDF

Bilingual Support

The site supports English and French through file naming:

• page.md - English version
• page.fr.md - French version

The i18n plugin automatically creates language switchers and separate builds.

Translation Workflow

1. Write content in English (e.g., docs/network/wifi.md)
2. Use the local Gemma translation script:

   python scripts/translate.py docs/network/wifi.md
   

3. Review and edit the generated French file (docs/network/wifi.fr.md)

Content Guidelines

Writing Style

• Clear, concise technical writing
• Use active voice
• Include practical examples
• Provide troubleshooting sections

Formatting

• Use Markdown headings (# ## ###)
• Use code blocks with language identifiers
• Use admonitions for warnings/tips:

  !!! warning "Title"
      Warning message
  

• Use tabs for alternative instructions:

  === "Option 1"
      Instructions for option 1
  === "Option 2"
      Instructions for option 2
  

Links

• Use relative paths: [Text](../path/page.md)
• Link to external resources with full URLs
• Keep links up to date

PDF Export

The PDF export:

• Includes all pages except admin/ section
• Automatically generated during deployment
• Can be built locally with ./build-pdf.sh
• Output: site/pdf/it-guide.pdf

Deployment

Automatic (Recommended)

Push to the main branch triggers automatic deployment via GitHub Actions:

git add .
git commit -m "Update documentation"
git push origin main

The site will be automatically built and deployed to GitHub Pages.

Downloadable Artifacts

Each GitHub Actions build creates downloadable artifacts:

1. it-guide-site: Complete HTML site with all assets and PDFs
2. it-guide-pdfs: PDF files only (English and French)

To download:

1. Go to the Actions tab
2. Click on the latest workflow run
3. Scroll to "Artifacts" section
4. Download the artifact you need

Artifacts are retained for 90 days.

Manual

# Build and deploy manually
mkdocs gh-deploy

Contributing

Adding New Pages

1. Create the page in the appropriate docs/ subdirectory
2. Add it to nav section in mkdocs.yml
3. Create French translation (optional, can be done later)
4. Test locally with ./serve.sh
5. Commit and push

Updating Content

1. Edit the relevant .md file in docs/
2. Test locally with ./serve.sh
3. Update French version if needed
4. Commit and push

Reporting Issues

• Use GitHub Issues
• Include: page URL, description, expected vs. actual behavior

Support

• Repository: github.com/ins-amu/it-guide
• Issues: github.com/ins-amu/it-guide/issues
• INS IT Support: support@ins.univ-amu.fr

License

Documentation content is maintained by INS IT Department.

---

Maintained by: INS IT Department Last Updated: 2024