Building a Scalable Documentation Site with Athena, EJS Templates, and Fixed Navigation

Framework Construction

To avoid repetitive manual edits across dozens of documentation pages, the team adopted the open‑source front‑end engineering tool Athena , which provides hot‑reloading previews, code compression, SASS/LESS compilation, and SFTP upload. By leveraging EJS template syntax, shared components such as headers, footers, and navigation bars can be referenced across all pages, dramatically reducing maintenance effort.

Document Entry Process

Entering a 104‑page DOC manual proved labor‑intensive. The team created granular EJS components for each style element (e.g., first‑level headings, second‑level headings) and used widget.load to inject them. An example component definition and usage is shown below:

<%= widget.load('doc_mod_list3', {title1:'操作指南',item1:['挂载云硬盘','绑定公网IP','常见问题','主机数量','监控报警','删除云主机','绑定监控报警','重置密码','制作镜像'],title2:'常见问题',item2:['主机数量','监控报警','删除云主机'],item3show:false}) %>

The component itself is an EJS template that iterates over the provided arrays to generate HTML lists.

Over‑Modularization Issue

While componentization improves reuse, creating excessively fine‑grained components (e.g., wrapping a simple <h3 class="doc_mod_title3">... tag in a component) made the entry workflow cumbersome without reducing code size. The article highlights that “over‑modularization leads to tiny components” and suggests a more streamlined approach.

Alternative Conversion Strategy

The author mentions the Python library docx2html , which converts DOCX files to clean HTML without inline styles. By assigning a single CSS class doc_mod_content to the converted content and styling descendants via selectors, the need for numerous custom components could be eliminated. Time constraints prevented this method from being adopted in the current project.

Navigation Optimization

Long documentation pages caused the side navigation to disappear from view when scrolling. The solution defines three navigation states:

Before the navigation reaches the top: position: static When the navigation scrolls past the top: position: fixed When the navigation reaches the bottom of the content: position: absolute; bottom: 0 (or JS‑controlled alignment)

Trigger conditions are based on the page’s scroll offset relative to the navigation bar and content height. The article also discusses the problem of highlighted items not staying visible after page jumps.

Practical Fixes

One workaround moves the highlighted menu item to the top of the navigation array using JavaScript:

// var menu, curIdx;
menu.unshift(menu.splice(curIdx/*highlight index*/, 1)[0]);
// menu.forEach(function (val, idx) {...});

Another suggestion is to load new documentation content via AJAX (JSON or HTML fragments) so the navigation bar remains static while only the content pane refreshes, improving perceived performance.

Reflection

The project left several ideas unimplemented due to time pressure, underscoring the importance of early collaboration with product, interaction, and visual teams. The author concludes that user experience should guide technical decisions rather than isolated engineering choices.