Enhancing Open Learning Platforms with MkDocs at HAMK

In higher education, teaching is increasingly becoming accessible 24/7. This poses challenges for classical educational environments. One way to solve this problem is to move teaching materials to open platforms where students can access the material at any time. This article discusses one such platform, Github Pages, which allows you to publish teaching materials easily and for free so that they are easily accessible to hundreds to thousands of students. Github Pages has already become one of many platforms for scientific publications due to its free cost and scalability.

Identifying the Challenges

The Business Information Technology and Computer Applications (BIT/CA) programmes at Häme University of Applied Sciences (HAMK) have traditionally relied on Moodle to host course materials. While Moodle is a powerful open-source virtual learning environment that supports online courses, content sharing, and student interaction, it has limitations when it comes to handling large volumes of documentation and code.

Despite its many add-ons and plugins, Moodle lacks flexibility when teaching coding, virtualization, and operating systems. Expanding its capabilities requires ongoing maintenance and is limited to HAMK’s students and staff. Seeking a more open and flexible solution, teachers initially transferred course materials to GitHub gists, repositories, and pages, linking them to Moodle. While this method has improved accessibility, it has also introduced usability and integration challenges, leading to confusion among students.

Recognizing these challenges, the BIT/CA programmes initiated research into alternative platforms and selected the second author of this article, Quang Luong, to contribute to the project by testing solutions and designing a more user-friendly template.

Implementing MkDocs with the Material Theme

To enhance the documentation experience, the project focused on implementing MkDocs with the Material theme. MkDocs is a static site generator which is simple, fast, and elegant for creating technical documentation. This approach introduced modern features essential for effective learning, including:

• dark/light mode switching
• built-in code highlighting
• line numbering
• a copy button for code snippets.

These features significantly improved usability for students and educators alike (Figures 1 & 2). As education increasingly embraces open-access resources, MkDocs offers a structured, interactive, and visually appealing platform for hosting teaching materials.

Project Roles and Contributions

Both authors played complementary roles in the project. Tero Keso initiated and supervised the project, ensuring alignment with HAMK’s broader goals of accessibility and open learning. Quang Luong focused on customizing Material for MkDocs to meet the specific needs of the BIT/CA programmes. With additional support from senior lecturer Deepak Kc, the team developed:

• A working MkDocs template
• A comprehensive documentation guide
• An updated BYOD (Bring Your Own Device) page reflecting HAMK’s branding

This setup introduced key functionalities such as enhanced search, interactive code examples, and multimedia support, making it especially beneficial for students in Business Information Technology and Computer Applications.

Integrating MkDocs with Moodle

The transition to MkDocs does not replace Moodle; rather, it complements it. Moodle remains the primary tool for assignments and discussions, while MkDocs-based materials are seamlessly integrated within it. This approach ensures that students have access to structured, up-to-date resources without disrupting the existing learning management system.

By bridging these two platforms, the project supports HAMK’s mission to provide open and accessible education. It fosters a collaborative learning environment that benefits not only HAMK students and degree programme but also the wider academic community.

Conclusion

This project extends beyond technical enhancements—it represents a meaningful step toward improving digital education at HAMK. By adopting MkDocs, we have created a more flexible and engaging platform that enhances both teaching and learning. Through this initiative, we support educators, empower students, and contribute to a future-ready approach to open learning.

---

Interested in this topic? Take a look at the related materials:

• The MkDocs template for HAMK BIT/CA material
• The documentation guide
• The BIT/CA BYOD page