Skip to content

mkdocs migration

Reporting any issues

Most issues with embedded content and links were manually fixed, but some problems may remain as an automated tool was used to convert the Mediawiki content into Markdown. Please report any issues to urcf-support@drexel.edu with the following information:

  • Page URL (ie https://some.page.drexel.edu/mkdocs_migration)
  • Description of what is wrong, what you were expecting

Issues that might be encountered:

  • Missing images
  • Missing file uploads
  • Broken links
  • Stale links to proteusmaster.urcf.drexel.edu

Goals

We have identified mkdocs as a reasonable alternative to Mediawiki, which is a simple documentation platform written in Python that converts YAML and content written in Markdown to static HTML and Javascript. The benefits of using mkdocs are quite clear:

  • Static site generation (no php, no database server required), greatly improving security posture of web application and server.
  • Storing content in internal IRT Gitlab instance, automated CI/CD processes running changes through yamllint to avoid breaking changes in order to deploy new site content upon commit.
  • Upon approval of URCF Board, the public-facing mkdocs instance for URCF could be opened to the world instead of being restricted to campus networks.

Migration Procedure

The migration procedure is as follows:

  • Using Mediawiki's maintenance backup PHP scripts to dump all content to XML
  • Using https://github.com/philipashlock/mediawiki-to-markdown to convert all content to Markdown
  • Creating mkdocs YAML config to generate navigation
  • Removing redirect pages as they do not work 1:1 functionally compared to Mediawiki
  • Migrating site assets/images (images, pdf's) to /assets directory
  • Fixing all image embeds (which are broken because of Mediawiki embed syntax vs Markdown), removing ones that do not work well with the way markdown formatting works
  • Testing all links and pages