Guide: Combining a Custom HTML Landing Page with MkDocs

If you want a unique, custom-coded HTML landing page while still using the power of MkDocs for weekly documentation, this guide explains how to set that up without breaking your GitLab pipeline.

🛠 Step 1: Organize Your Folder Structure

To prevent files from clashing, you must separate your "Landing Page" source from your "Documentation" source. Arrange your repository like this:

  • custom_landing/: Put your custom index.html, style.css, and images here.
  • docs/: Put your weekly Markdown files (e.g., week01.md) and your documentation index.md here.
  • mkdocs.yml: Your MkDocs configuration file (keep this in the root).
  • .gitlab-ci.yml: Your GitLab automation instructions (keep this in the root).

⚙️ Step 2: Configure the .gitlab-ci.yml

GitLab needs a "recipe" to build your site. This specific configuration ensures Python is available and moves your files to the correct place.

Replace everything in your .gitlab-ci.yml with this:

image: python:latest

pages:
  stage: deploy
  script:
    - pip install mkdocs
    # 1. Build the MkDocs site into a subfolder
    - mkdocs build --site-dir public/docs
    # 2. Copy the custom landing page to the main root
    - cp -r custom_landing/. public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

💻 Step 3: Pushing Changes via VS Code

When you move or delete files to organize your repo, you must tell Git to "record" those changes.

  1. Open Source Control: Click the branch icon on the left sidebar in VS Code.
  2. Stage All Changes: Hover over the Changes section and click the + (plus) icon. This stages everything—new files, moves, and deletions.
  3. Commit: Type a clear message in the box (e.g., "Setup custom landing page and MkDocs structure") and click Commit.
  4. Sync: Click Sync Changes (or the circular arrow icon) at the bottom left to push to GitLab.

🔍 Step 4: Verify the Build

  1. Go to your GitLab project online.
  2. Navigate to Build > Pipelines.
  3. Blue (Running): Wait 1-2 minutes.
  4. Green (Passed): Success!
  5. Red (Failed): Click the red badge, click the "pages" job, and check the bottom of the log for errors (usually a typo or a missing folder).

🔗 Step 5: Linking Everything Together

Now that your site has two parts, your links must be correct:

  • From Landing Page to Docs: In your custom_landing/index.html, your link should look like this: <a href="docs/index.html">View My Documentation</a>

  • From Docs to Landing Page: In your mkdocs.yml, you can add a link back to your home page:YAML

    extra: homepage: ../index.html

💡 Top Tips for Success

  • Case Sensitivity: Linux servers care about capitals! Custom_Landing is not the same as custom_landing. Pick one and stay consistent.
  • The "Busybox" Error: If your pipeline says pip: command not found, it means your .gitlab-ci.yml is missing the image: python:latest line at the very top.
  • Wait for the Refresh: After a green pipeline, wait about 60 seconds for the website to actually update.