Skip to main content

Documentation Setup

This documentation site is built with Docusaurus and runs independently from the HRMS application.

Prerequisites​

  • Node.js 18+ (20+ recommended)
  • npm 10+

Install and Run​

cd c:\laragon\www\hrms-docs
npm install
npm start

The docs site opens at http://localhost:3000.

Port Conflict

If the HRMS frontend is also running on port 3000, start the docs on a different port:

npm start -- --port 4000

Build Static Output​

npm run build

This generates a build/ directory with static HTML, CSS, and JS files.

Preview the Build​

npm run serve

Folder Structure​

hrms-docs/
├── docs/                   # Markdown documentation pages
│   ├── intro.md            # Landing page (/)
│   ├── setup/              # Setup guides
│   ├── architecture/       # Technical architecture
│   ├── user-guide/         # End-user task guides
│   ├── modules/            # Module-level documentation
│   ├── roles/              # Role-based access documentation
│   ├── api/                # API documentation & reference
│   └── changelog/          # Release notes
├── static/
│   └── img/                # Images, logos, screenshots
│       └── screenshots/    # Add screenshots here
├── src/
│   └── css/custom.css      # Theme customizations
├── docusaurus.config.ts    # Site configuration
├── sidebars.ts             # Sidebar navigation structure
└── package.json

Adding or Editing Pages​

  1. Create or edit a .md file in the docs/ directory.
  2. Add YAML frontmatter at the top:
---
sidebar_position: 3
title: Page Title
description: Brief description for SEO and link previews.
---

# Page Title

Your content here.
  1. If the page belongs to a new section, register it in sidebars.ts.
  2. The dev server hot-reloads — changes appear immediately.

Adding Screenshots​

  1. Place image files in static/img/screenshots/.
  2. Reference them in markdown:
![Employee list page](/img/screenshots/employee-list.png)

Screenshots are optional — all documentation reads well without them and can be enriched later.

Deployment​

The site is designed for local-first usage. When ready to deploy to a server:

  1. Run npm run build.
  2. Copy the build/ directory to the web server's document root.
  3. Configure the server to serve index.html for all routes (SPA fallback).
  4. If deploying to a subdirectory (e.g., /docs/), update baseUrl in docusaurus.config.ts:
baseUrl: '/docs/',
  1. Update the url field to match the production domain.
  2. Rebuild and redeploy.

Contribution Guidelines​

  • Keep pages focused — one topic per page.
  • Use task-oriented language for user guides ("How to create an employee").
  • Use accurate, concise language for technical docs.
  • Mark unimplemented features with a clear admonition:
:::info[Not Yet Implemented]
This feature is planned for a future phase and is not available in the current release.
:::
  • Update the changelog when features ship.