{"id":48293499,"url":"https://github.com/jwilleke/ngdpbase","last_synced_at":"2026-05-21T14:01:21.461Z","repository":{"id":314279764,"uuid":"1051358905","full_name":"jwilleke/ngdpbase","owner":"jwilleke","description":"A markdown based Next Generation Digital Platform","archived":false,"fork":false,"pushed_at":"2026-04-28T18:06:58.000Z","size":25686,"stargazers_count":2,"open_issues_count":31,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-28T20:12:16.965Z","etag":null,"topics":["dam","document-management","journal","markdown","wiki"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jwilleke.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-05T21:11:42.000Z","updated_at":"2026-04-28T18:07:02.000Z","dependencies_parsed_at":"2025-09-11T16:17:58.111Z","dependency_job_id":"0e490e81-a221-4194-b450-540e9a0bc5b1","html_url":"https://github.com/jwilleke/ngdpbase","commit_stats":null,"previous_names":["jwilleke/amdwiki"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/jwilleke/ngdpbase","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwilleke%2Fngdpbase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwilleke%2Fngdpbase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwilleke%2Fngdpbase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwilleke%2Fngdpbase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jwilleke","download_url":"https://codeload.github.com/jwilleke/ngdpbase/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwilleke%2Fngdpbase/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32534972,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dam","document-management","journal","markdown","wiki"],"created_at":"2026-04-04T23:24:38.347Z","updated_at":"2026-05-15T13:06:00.283Z","avatar_url":"https://github.com/jwilleke.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ngdpbase\n\nA file-based wiki application built with **Node.js**, **Express**, **TypeScript**, and **Markdown**, inspired by [JSPWiki](https://github.com/apache/jspwiki).\n\n📋 **See [docs/planning/ROADMAP.md](docs/planning/ROADMAP.md) for project vision, technical specifications, and feature priorities.**\n\n## Features\n\n- Create, view, and edit wiki pages\n- Advanced search with multi-criteria filtering\n- JSPWiki-style link syntax with pipe notation\n- Category and keyword-based organization\n- Red link detection for non-existent pages\n- Three-state authentication system\n- Professional UI with Bootstrap styling\n- Pages are stored as Markdown files\n- **Inline image support with upload functionality**\n- **Plugin system for extensible functionality**\n- **Policy-Based Access Control**: Advanced permission system with JSON configuration\n- **Comprehensive Audit Trail**: Complete security monitoring and access logging\n- **Time-Based Permissions**: Context-aware permissions with scheduling and maintenance mode\n- **Admin Dashboard**: Full administrative interface for user management and system monitoring\n- **WikiDocument DOM Architecture**: Robust, JSPWiki-inspired parsing engine with DOM-based processing\n- **Conflict-Free Parsing**: JSPWiki syntax and Markdown coexist without interference\n- **📚 Page Version History**: Complete version control with diff comparison and restore capabilities\n  - View all previous versions of any page\n  - Compare versions side-by-side or unified diff\n  - Restore to any previous version\n  - Automatic delta storage for efficiency\n  - Full version metadata tracking\n- **🤖 Model Context Protocol (MCP) Server**: AI assistant integration for enhanced productivity\n  - Direct AI access to wiki content and metadata\n  - Full-text search with advanced filtering\n  - Metadata validation and generation\n  - 12 specialized tools for wiki operations\n  - Integration with Claude Desktop and Claude Code CLI\n\n📖 **Detailed technical documentation available in [docs/](docs/) folder.**\n\n## Getting Started\n\n### For Users\n\n1. Install dependencies:\n\n    ```bash\n    npm install\n    ```\n\n2. Start the server:\n\n    ```bash\n    ./server.sh start          # Production mode (default)\n    # or\n    ./server.sh start dev      # Development mode\n    ```\n\n3. Open your browser and navigate to `http://localhost:3000`\n\n**Server Management:**\n\n```bash\n./server.sh start [dev|prod]   # Start server (default: production)\n./server.sh stop               # Stop server\n./server.sh restart [dev|prod] # Restart server\n./server.sh status             # Show server status\n./server.sh logs [50]          # Show logs (default: 50 lines)\n./server.sh env                # Show environment config\n./server.sh unlock             # Remove PID lock (if server crashed)\n```\n\n### For Developers\n\n- Follow the setup steps above\n- The codebase uses **TypeScript with strict mode** enabled\n- Read [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards, TypeScript guidelines, and contribution guidelines\n- Check [CHANGELOG.md](CHANGELOG.md) for version history and migration notes\n\n**TypeScript Commands:**\n\n```bash\nnpm run typecheck       # Type checking (no output)\nnpm run build           # Build TypeScript to JavaScript\nnpm run build:watch     # Watch mode for development\nnpm test                # Run all tests (supports .ts and .js)\n```\n\n### For AI Integration (MCP Server)\n\nngdpbase includes a Model Context Protocol (MCP) server for AI assistant integration:\n\n```bash\n# Build TypeScript\nnpm run build\n\n# Start MCP server\nnpm run mcp\n```\n\n**Integration with Claude Desktop:**\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ngdpbase\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/ngdpbase/dist/mcp-server.js\"],\n      \"cwd\": \"/path/to/ngdpbase\"\n    }\n  }\n}\n```\n\n📖 **See [docs/MCP-SERVER.md](docs/MCP-SERVER.md) for complete documentation.**\n\n## Configuration\n\nngdpbase uses a **hierarchical configuration system** with three layers (later overrides earlier):\n\n1. `config/app-default-config.json` - Base defaults (required, ~1150 properties)\n2. `config/app-{environment}-config.json` - Environment-specific settings (optional)\n   - Environment determined by `NODE_ENV` (development, production, test)\n3. `config/app-custom-config.json` - Local overrides (optional, persisted by admin UI)\n\n### Making Configuration Changes\n\n**Via Admin UI:**\n\n- Navigate to [/admin/configuration](/admin/configuration)\n- Changes saved to `app-custom-config.json`\n- Restart required: [/admin/restart](/admin/restart)\n\n**Manual Editing:**\n\n- Edit `config/app-custom-config.json` directly\n- Restart server to apply changes:\n\n  ```bash\n  ./server.sh restart\n  ```\n\n### Key Configuration Properties\n\n```json\n{\n  \"ngdpbase.application-name\": \"ngdpbase\",\n  \"ngdpbase.server.port\": 3000,\n  \"ngdpbase.base-url\": \"http://localhost:3000\",\n  \"ngdpbase.front-page\": \"Welcome\",\n  \"ngdpbase.page.provider\": \"filesystemprovider\",\n  \"ngdpbase.backup.auto-backup\": true\n}\n```\n\n**Note:** Properties starting with `_` are treated as comments and ignored.\n\n### Operator Guides\n\nFor deploy-time and runtime operator topics see `docs/admin/`:\n\n- [Self-Registration](./docs/admin/Self-Registration.md) — disable the public `/register` form\n- [Email Setup](./docs/admin/email-setup.md) — outbound mail (magic-link login, contact form)\n- [Backups](./docs/admin/Backups.md) — backup configuration\n- [Telemetry](./docs/admin/Telemetry.md) — metrics and observability\n- [Versioning Deployment Guide](./docs/admin/Versioning-Deployment-Guide.md) — page-versioning storage layout\n\n## Project Structure\n\n```bash\nngdpbase/\n├── src/                    # Source code\n│   ├── core/              # Core engine components\n│   ├── managers/          # 30 domain-specific managers\n│   ├── plugins/           # Auto-discovered plugin modules\n│   ├── providers/         # Storage provider implementations\n│   ├── parsers/           # WikiDocument DOM parser\n│   │   ├── dom/          # DOM handlers and WikiDocument\n│   │   └── __tests__/    # Parser test suites\n│   ├── routes/            # HTTP route handlers\n│   ├── types/             # Shared TypeScript interfaces\n│   └── utils/             # Utility functions\n├── addons/                # Domain addon packages (calendar, forms, journal, elasticsearch)\n├── config/                # Application configuration\n│   ├── app-default-config.json        # Base defaults (~1150 properties)\n│   ├── app-{env}-config.json          # Environment-specific\n│   └── app-custom-config.json         # Local overrides\n├── public/                # Static assets (CSS, JS, images)\n├── views/                 # EJS templates\n├── docs/                  # Documentation\n│   ├── architecture/      # System architecture docs\n│   ├── development/       # Development guides\n│   ├── planning/          # Project planning docs\n│   ├── api/              # API documentation\n│   ├── migration/        # Migration guides\n│   ├── testing/          # Testing documentation\n│   └── managers/         # Manager documentation\n├── scripts/               # Utility scripts\n├── templates/             # Wiki page templates\n├── themes/                # UI themes\n├── required-pages/        # System pages seeded on first boot\n├── data/                  # All instance-specific runtime data\n│   ├── pages/            # User-created wiki pages\n│   ├── users/            # User accounts and profiles\n│   ├── attachments/      # Uploaded file storage\n│   ├── backups/          # System backups (BackupManager)\n│   ├── logs/             # Application logs\n│   ├── sessions/         # Express session store\n│   └── search-index/     # Search index files\n├── exports/               # Exported content\n├── reports/               # Test coverage reports\n└── coverage/              # Istanbul coverage data\n```\n\n📖 **Detailed project structure documentation available in [docs/architecture/PROJECT-STRUCTURE.md](docs/architecture/PROJECT-STRUCTURE.md)**\n\n## Examples\n\n**Creating a Wiki Page Link (JSPWiki Syntax):**\n\n```markdown\n[Link Text|PageName]  # Links to PageName with custom text\n[PageName]           # Simple link to PageName\n```\n\n**Inserting Images (JSPWiki Plugin Syntax):**\n\n```markdown\n[{Image src='image.jpg' alt='Description' width='300'}]  # Basic image\n[{Image src='/images/photo.jpg' alt='Photo' height='200'}]  # With height\n[{Image src='https://example.com/image.png' class='responsive'}]  # External image\n```\n\n**Image Upload:**\n\n- Use the image upload section in the page editor\n- Select an image file and click \"Upload Image\"\n- Click \"Insert at Cursor\" to add the image to your content\n- Supported formats: JPEG, PNG, GIF, WebP (max 5MB)\n\n## Parser Architecture\n\nngdpbase uses a **WikiDocument DOM extraction pipeline** that provides robust, conflict-free parsing of JSPWiki syntax and Markdown:\n\n### How It Works\n\n1. **Extract** - JSPWiki syntax (`[{$var}]`, `[{Plugin}]`, `[Link]`) extracted before Markdown parsing\n2. **Create DOM Nodes** - WikiDocument DOM nodes created for each JSPWiki element\n3. **Parse Markdown** - Showdown processes ALL Markdown without JSPWiki interference\n4. **Merge** - DOM nodes merged back into final HTML\n\n### Benefits\n\n- ✅ **No parsing conflicts** - JSPWiki and Markdown processed independently\n- ✅ **Correct heading rendering** - All Markdown headings (`##`, `###`) render properly\n- ✅ **Natural escaping** - `[[{$var}]]` creates literal text via DOM nodes\n- ✅ **Extensible** - Easy to add custom syntax via DOM handlers\n- ✅ **Production-ready** - 376+ tests with 100% success rate\n\n### Parser Configuration\n\nThe WikiDocument DOM parser is enabled by default. To use the legacy parser, add to `config/app-custom-config.json`:\n\n```json\n{\n  \"jspwiki.parser.useExtractionPipeline\": false\n}\n```\n\nThen restart the server (see [Configuration](#configuration) section above).\n\n### Documentation\n\n- **API Reference:** [docs/api/MarkupParser-API.md](docs/api/MarkupParser-API.md)\n- **Migration Guide:** [docs/migration/WikiDocument-DOM-Migration.md](docs/migration/WikiDocument-DOM-Migration.md)\n- **Architecture:** [docs/architecture/WikiDocument-DOM-Architecture.md](docs/architecture/WikiDocument-DOM-Architecture.md)\n\n## Documentation\n\n- [CHANGELOG.md](CHANGELOG.md) - Version history and detailed change notes.\n- [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute to the project.\n- [ROADMAP.md](ROADMAP.md) - Project vision and feature priorities.\n- [docs/](docs/) - In-depth technical guides on architecture, plugins, and more.\n\n## Version Management\n\nThis project follows [Semantic Versioning](https://semver.org/) (SemVer). Use the built-in version management tools:\n\n### Check Current Version\n\n```bash\nnpm run version:show\n# or\nnode scripts/version.js\n```\n\n### Increment Version\n\n```bash\nnpm run version:patch    # Bug fixes (1.2.0 → 1.2.1)\nnpm run version:minor    # New features (1.2.0 → 1.3.0)\nnpm run version:major    # Breaking changes (1.2.0 → 2.0.0)\n```\n\n### Set Specific Version\n\n```bash\nnode scripts/version.js set 1.2.3\n```\n\n### Version Help\n\n```bash\nnpm run version:help\n```\n\nThe version management script automatically:\n\n- Updates `package.json` version\n- Updates `CHANGELOG.md` with release information\n- Validates version format\n- Provides semantic versioning guidance\n\n## License\n\nSee [LICENSE](LICENSE) for details on usage and distribution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwilleke%2Fngdpbase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjwilleke%2Fngdpbase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwilleke%2Fngdpbase/lists"}