Skip to content

Bilingual Site Launch

Ticket #84 + #85: Recovery, Restructuring, and Deployment of Technical Documentation
Type: Recovery / Refactoring / Infrastructure
Affected Components: Project Structure, mkdocs.yml, GitHub Actions, Nginx Config

1. Context and Strategic Objective

The objective of the work documented in this report was to transition from monolingual to bilingual documentation (EN/FR) on docs.invest.justingoufo.com. Situation History: A first attempt to implement bilingualism and footer customization, entrusted to the AI Agent (Gemini) in Firebase Studio, was marked by severe technical hallucinations, to the point of breaking the site structure, rendering it inoperable (Error 403). Change of Approach: This report documents the recovery of the project via a directed investigation strategy on Google AI Studio to audit the damage, sanitize the architecture, ensure reliable deployment, and restore the site.

2. Investigation and Refactoring Process

  1. Post-Incident Audit:

    • Observation: The project architecture was fragmented (source files buried in project_docs), making maintenance complex.
    • i18n Blocker: The folder structure (different names in FR and EN) was incompatible with the translation plugin, a likely aftermath of the previous attempt.

  2. File System Refactoring (Standardization):

    • Action: Removal of the superfluous project_docs layer to move configuration back to the root.
    • Action: "Mirror" normalization of filenames. French files were renamed to exactly match English names (e.g., adoption of activity_report for both languages), a sine qua non condition for the plugin to function.

  3. MkDocs Configuration Fix:

    • Action: Abandonment of implicit automatic translation in favor of an explicit override of the menu in the configuration file. This allowed restoring French titles and navigation that had been lost.

  4. CI/CD Pipeline Debugging (GitHub Actions):

    • Error: The pipeline failed following file moves.
    • Correction: Update paths in the workflow (deploy-docs.yml) and explicit addition to the repository of dependency files (docs-requirements.txt) that had been omitted.

  5. Resolution of Deployment Incident (Nginx 404 Error):

    • Symptom: Site inaccessible despite a successful build.
    • Root Cause: Desynchronization between the target folder defined in GitHub Secrets and the Nginx server configuration.
    • Correction: Creation of the physical directory tree on the VPS and alignment of the DOCS_TARGET_DIR Secret.

3. Root Cause Identified (Summary)

The project instability resulted from technical debt introduced by poorly supervised automation: inconsistent file structure, erroneous i18n configuration, and disconnection between source code and deployment infrastructure.

4. Implemented Solution

  • Sanitized Architecture: Clean bilingual structure (docs/ and docs/fr/) with strict file correspondence.
  • Regained Control: Manual and explicit configuration of mkdocs.yml to ensure stability.
  • Infrastructure: CI/CD pipeline and Nginx server perfectly synchronized.

5. Justification and Benefits

  • Service Restoration: The documentation is back online and functional.
  • Reliability: The project has emerged from the unstable state left by the AI agent. The current architecture is standardized, facilitating future updates by humans.
  • User Experience: Language switching and navigation are now fluid and error-free.