(we are switching to a new theme,
don't worry if things look different for a while!)

Site Navigation

Plans

Massive Wiki Roadmap
Pier2Pier
Massive Wiki Builder redesign

For Testing

wiki link test page
Mistletoe parser test page
Mistletoe & the ampersand story

Edit on GitHub


NXC User Guide

This document provides a comprehensive guide to using the NXC (Massive Wiki Builder) static site generator.

Getting Started

Installation

Install NXC using pip:

pip install --extra-index-url https://test.pypi.org/simple/ nxc

For search functionality, you'll need Node.js installed.

Creating a New Wiki

Initialize a new wiki with the init command:

nxc init my-wiki

This will:

  1. Create the my-wiki directory if it doesn't exist
  2. Set up the .nxc directory with configuration files
  3. Copy template files (Sidebar.md, .gitignore, etc.)
  4. Prompt for wiki title, author, and repository URL
  5. Create a configuration file at .nxc/nxc.yaml

Basic Structure

After initialization, your wiki will have this structure:

my-wiki/
├── .nxc/
│   ├── nxc.yaml                 # Configuration file
│   ├── build-index.js           # Search indexer
│   ├── package.json             # Node.js dependencies
│   └── this-website-themes/     # HTML templates
├── .gitignore                   # Git ignore file
├── Sidebar.md                   # Wiki sidebar content
└── netlify.toml                 # Netlify configuration

Adding Content

Create Markdown files in your wiki directory:

# Example files
touch my-wiki/Home.md
touch my-wiki/About.md
touch my-wiki/Projects.md

Linking Between Pages

Use wiki-style double-bracket links:

<!-- Basic link -->
Visit the [[About]] page for more information.

<!-- Link with custom text -->
Learn about our [[Projects|current projects]].

Including Images

Images can be included using:

<!-- Basic image -->
![[logo.png]]

<!-- Image with alt text -->
![[screenshot.png|Screenshot of the application]]

Transcluding Content

Include content from other pages:

<!-- Include content from another page -->
![[ProjectSummary]]

YAML Front Matter

Add metadata to pages with YAML front matter:

---
title: Project Overview
date: 2023-01-15
author: Jane Smith
tags: [project, documentation]
---

# Project Overview

Content starts here...

Building Your Wiki

Build your wiki into a static site:

nxc build -i my-wiki -o my-wiki-site

Options:

Configuration

The .nxc/nxc.yaml file controls your wiki's behavior:

wiki_title: My Wiki
author: Your Name
repo: <a href="https://github.com/username/repo">repo</a>
license: <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC-BY-SA 4.0</a>
sidebar: Sidebar.md
edit_url: https://github.com/username/repo/edit/
edit_branch: main
excluded_directories:
  - .git
  - .nxc
recent_changes_count: 5

Customizing Appearance

Templates

NXC uses the Jinja2 templating system. The default theme is "dolce".

To customize, edit files in .nxc/this-website-themes/dolce/:

CSS and JavaScript

Custom styles and scripts go in:

Advanced Features

Search

Enable full-text search with the --lunr flag:

nxc build -i my-wiki -o my-wiki-site --lunr

This requires Node.js and will generate JavaScript files for client-side search.

Git Integration

Use the --commits flag to include Git commit information:

nxc build -i my-wiki -o my-wiki-site --commits

This will:

Deployment

NXC generates a static site that can be deployed anywhere:

Troubleshooting

Common Issues