Creating Your First Project

Create a new Mordoc documentation project using the CLI tool and explore the generated starter template.

3 min read

Creating Your First Project

Mordoc provides a CLI tool that scaffolds a complete documentation project with a pre-configured template. You'll have a working documentation site in minutes.

Create a New Project

Use the create-mordoc-app command to generate a new project:

Bash

npx create-mordoc-app my-docs

Replace my-docs with your preferred project name.

What is npx?

npx is a package runner tool that comes with npm. It downloads and executes the latest version of create-mordoc-app without requiring a global installation.

Interactive Setup

The CLI will guide you through the setup process:

Project Name: Confirm or modify the project name
Template Selection: Choose a starter template (default template is recommended for beginners)
Install Dependencies: The tool will automatically install required npm packages

Example Output

Bash

$ npx create-mordoc-app my-docs

✓ Creating Mordoc project...
✓ Copying template files...
✓ Installing dependencies...

Success! Created my-docs at /path/to/my-docs

Inside that directory, you can run several commands:

  npm run dev
    Starts the development server

  npm run build
    Builds the site for production

  npm run preview
    Previews the production build locally

Get started by typing:

  cd my-docs
  npm run dev

Navigate to Your Project

Bash

cd my-docs

Start the Development Server

Launch the local development server:

Bash

npm run dev

Your documentation site will be available at:

http://localhost:3000

The development server includes:

Hot Reload: Changes to markdown files automatically refresh the browser
Live Preview: See your edits in real-time
Error Reporting: Console errors for syntax issues

Keep the development server running while you work. Press Ctrl+C to stop it when you're done.

What Gets Created

The create-mordoc-app command generates a complete project structure:

my-docs/
├── config/
│   ├── sidenav.yaml
│   ├── site.json
│   └── styles/
│       ├── main.json
│       └── typography.json
├── content/
│   └── en/
│       └── index.md
├── public/
│   ├── images/
│   └── icons/
├── package.json
└── node_modules/

Key Directories

Directory	Purpose
`config/`	Configuration files for navigation, styling, and site settings
`content/`	Your markdown documentation files
`public/`	Static assets like images, icons, and custom files
`node_modules/`	Dependencies (auto-generated, don't edit)

Understanding the Template

The starter template includes:

Sample Content: Example markdown files demonstrating Mordoc features
Pre-configured Navigation: A working sidenav structure
Default Styling: Professional theme with customizable colors
Example Assets: Sample images and icons

You can modify or replace any of these files to match your documentation needs.

Customize Your Site

Update Site Information

Edit config/site.json to set your site metadata:

Json

{
  "title": "My Documentation",
  "description": "Documentation for my awesome project",
  "baseUrl": "https://docs.myproject.com",
  "language": "en"
}

Add Your Logo

Replace the default logo files in config/:

logo.png - Light mode logo
logo-dark.png - Dark mode logo
favicon.ico - Browser favicon

Start Writing Content

Create new markdown files in content/en/ and update config/sidenav.yaml to add them to your navigation.

Next Step

Learn about the project structure to understand how all these pieces work together.

Common Issues

Port Already in Use

If port 3000 is already occupied:

Bash

# The dev server will automatically try the next available port
# Or specify a custom port:
npm run dev -- --port 3001

Permission Errors

If you encounter permission errors during installation:

Bash

# Try using sudo (macOS/Linux)
sudo npx create-mordoc-app my-docs

# Or fix npm permissions first
npm config set prefix ~/.npm-global

Template Not Found

Ensure you have an active internet connection. The CLI downloads the latest template from the registry.

Next Steps

Now that your project is created: