简体中文 | English

NavPress is a powerful CLI tool for generating beautiful static navigation websites. Build your personal navigation site in minutes with a simple configuration file. Perfect for developers, teams, and anyone who wants to organize their favorite links.

• 🎯 Simple Configuration: Define your navigation and sidebar through a single configuration file
• ⚡ Hot Reload: Configuration changes apply instantly during development
• 🏗️ Production Ready: Built-in SSR support, automatically generates static HTML files
• 🎨 Modern Stack: Built with Vue.js 3 and Tailwind CSS
• 📱 Responsive Design: Perfect for desktop and mobile devices
• 🔗 Flexible Routing: Support multiple URL formats (query, path, hash)
• 🖼️ Built-in Icons: Default icons included, custom icons supported
• 🚀 CLI Tool: Easy-to-use command line interface
• 📦 Zero Dependencies: Lightweight and fast
• 🔄 Automated CI/CD: GitHub Actions for automatic npm publishing and GitHub Pages deployment

View Demo

npm install -g navpress@latest

# Using yarn
yarn global add navpress@latest

# Using pnpm
pnpm add -g navpress@latest

# Local development
npm install navpress@latest --save-dev

navpress --version
# Output: [email protected]

Create navpress.config.js in your project root:

export default {
  title: 'My Navigation',
  description: 'Personal website navigation',
  logo: '/images/logo.svg',
  base: '/',

  sidebar: [
    {
      text: 'Development Tools',
      link: '/tools',
      items: [
        {
          text: 'Frontend Frameworks',
          link: '#frameworks',
          items: [
            {
              text: 'Vue.js',
              link: 'https://vuejs.org',
              description: 'Progressive JavaScript Framework',
            },
            {
              text: 'React',
              link: 'https://reactjs.org',
              description: 'JavaScript library for building user interfaces',
            },
          ],
        },
      ],
    },
  ],
}

# If installed globally
navpress dev

# If installed locally
npx navpress dev

# Build static files
navpress build

# Built files will be in dist directory

sidebar: [
  {
    text: 'Category Name',
    link: '/category', // Category page path
    icon: '/icon.svg', // Optional: custom icon
    items: [
      {
        text: 'Sub Group',
        link: '#section', // Anchor link
        items: [
          {
            text: 'Website Name',
            link: 'https://example.com',
            icon: '/site-icon.svg', // Optional
            description: 'Website description', // Optional
          },
        ],
      },
    ],
  },
]

• query (Recommended): /tools?section=frameworks - Uses query parameters
• path: /tools/frameworks - Uses path parameters
• hash: /tools#frameworks - Uses hash parameters

# Build your site
navpress build

# Deploy to any static hosting service
# The built files are in the `dist` directory

1. Fork this repository
2. Enable GitHub Pages in repository settings
3. Select gh-pages branch as source
4. Modify navpress.config.js with your configuration

# Build and deploy
navpress build
# Drag and drop the `dist` folder to Netlify

# Install Vercel CLI
npm i -g vercel

# Deploy
navpress build
vercel --prod

navpress build
# Upload the `dist` directory to your hosting service

npm run dev      # Vite dev server (source code HMR, fast iteration)
npm run build    # Build src/ → dist/ (pre-built assets)
npm run preview  # Build + serve with CLI (same as end-user experience)
npm run lint     # Run linting
npm run format   # Format code

npm run dev      →  Edit source code with Vite HMR
npm run preview  →  Verify the CLI serves pre-built dist/ correctly
npm link         →  Test in a real consumer project (optional)

npm run preview is the key command — it builds dist/ and then starts the CLI dev server, giving you the exact same experience as a user who installed navpress from npm.

navpress/
├── bin/
│   └── navpress.mjs          # CLI entry point
├── src/
│   ├── main.js               # App entry (config loading + HMR)
│   ├── App.vue               # Root component (layout)
│   ├── components/            # Vue components
│   ├── pages/                 # Page components
│   ├── utils/                 # Utility functions
│   ├── assets/                # Static assets & styles
│   ├── router/                # Vue Router config
│   └── node/                  # SSR prerender
├── vite.config.js             # Vite config (with hot reload plugin)
├── tailwind.config.cjs        # Tailwind CSS config
├── navpress.config.js         # Demo configuration
├── index.html                 # HTML template
└── package.json

For detailed development guide, see Contributing Guide.

Set the icon field in configuration:

{
  text: 'Website Name',
  link: 'https://example.com',
  icon: '/path/to/icon.svg'  // or https://example.com/icon.png
}

Set the base field:

export default {
  base: '/my-nav/', // Deploy to yoursite.com/my-nav/
  // ...other config
}

Create multiple configuration files and use different build commands:

# English version
navpress build --config navpress.en.js

# Chinese version
navpress build --config navpress.zh.js

# Update to latest version
npm update -g navpress@latest

# Or reinstall
npm install -g navpress@latest

npm uninstall -g navpress

navpress --version
# or
npm list -g navpress

NavPress uses GitHub Actions for automated deployment and publishing:

• 📦 npm Publishing: Include publish in your commit message

  git commit -m "feat: add new feature [publish]"

• 🌐 GitHub Pages: Include deploy in your commit message

  git commit -m "docs: update documentation [deploy]"

• 🔄 Regular Commits: No special identifier needed (won't trigger deployment)

1. npm Publishing (publish identifier):

   • Bumps version automatically
   • Publishes to npm registry
   • Creates GitHub release
   • Tags the release

2. GitHub Pages (deploy identifier):

   • Builds the project
   • Deploys to GitHub Pages
   • Updates live demo site

We welcome contributions! Please read our Contributing Guide for details on how to submit pull requests, report issues, and contribute to the project.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: yarn test
5. Commit your changes: git commit -m 'feat: add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

# Clone and setup
git clone https://github.com/aaronlamz/navpress.git
cd navpress
yarn install

# Start development
yarn dev

Found a bug? Have a feature request? Please create an issue and we'll get back to you!

MIT License - see the LICENSE file for details.

If you find NavPress helpful, please consider:

• ⭐ Starring this repository
• 📦 Installing from npm: npm install -g navpress@latest
• 🐛 Reporting bugs or suggesting features
• 🤝 Contributing code or documentation

Made with ❤️ by aaronlamz