mostage

v1.5.19

Published

2 months ago

Presentation framework based on markdown with HTML support and multi-format export capabilities.

Mostage

Presentation framework based on Markdown and HTML (Core Library + CLI)

Available as a NPM Package, CLI and Editor

Website | Demo | Quick Start | Development

CLI Editor Demo

Key Features

Markdown based - Write slides in Markdown with HTML support
Multiple Themes - Built-in themes: light, dark, dracula, ocean, rainbow
Plugin System - Extensible with plugins (progress bar, slide numbers, confetti, etc.)
Custom Backgrounds - Support for images, colors, and animations
Interactive Elements - Support for interactive content and animations
Multi-format Export - Export to HTML, PDF, PPTX, PNG, and JPG formats

Quick Start

Option 1: Using CLI

Using npx (no installation required)

# Create a new project
npx mostage@latest new

# Start development server
npx mostage@latest dev

# Start development server for specific project
npx mostage@latest dev --source /path/to/project

# Try demo presentation
npx mostage@latest example --template demo
npx mostage@latest dev --source mostage-demo

# Display help
npx mostage@latest help

Install globally

# Install CLI
npm install -g mostage

# Create a new project
mostage new

Note: You can use the interactive command (just run mostage new and follow the prompts), or provide options directly (e.g., mostage new --theme dracula --content-path content.md) to create presentations.

CLI Commands

You can use these commands with npx mostage@latest <command>:

| Command | Description | Options | | ----------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | mostage new | Create a new presentation project | --name, --content-path, --config-path, --theme, --plugins, --transition, --url-hash, --center-horizontal, --center-vertical | | mostage example | Create a new presentation project from examples | --template | | mostage dev | Start development server with live reload | --port, --host, --source | | mostage export | Export presentation in various formats | --source, --format, --output | | mostage theme | Manage themes (list, add, remove) | --list, --add, --remove | | mostage plugin | Manage plugins (list, add, remove) | --list, --add, --remove | | mostage help | Show help and command information | |

Project Creation

The mostage new command creates a new custom project:

# Interactive mode
mostage new

# Non-interactive mode with basic options
mostage new --name my-presentation --theme dark --transition horizontal

Export Presentations

The mostage export command allows you to export presentations in various formats:

mostage export # Export as single HTML (default)
mostage export --format pdf
mostage export --format pptx
mostage export --format png
mostage export --format jpg
mostage export --source ./my-project --format pdf --output ./my-exports

For detailed CLI documentation, see the CLI Commands section above.

Option 2: NPM Package Installation

Install Mostage as a dependency in your project:

npm install mostage@latest

Then import and use it in your project:

import Mostage from "mostage";

//Use internal config or path of external config
const presentation = new Mostage("./config.json");

presentation.start();

Or with CommonJS:

const Mostage = require("mostage");

const presentation = new Mostage("./config.json");

presentation.start();

Option 3: Manual Setup

If you prefer not to use the CLI or npm package, you can set up Mostage manually:

Create your project structure:

my-presentation/
├── index.html (With an internal configuration or an external configuration link)
├── content.md (slides)
└── config.json (Optional)

Create index.html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>My Presentation</title>
    <link
      rel="stylesheet"
      href="https://unpkg.com/mostage@latest/dist/core/mostage.css"
    />
  </head>
  <body>
    <div id="app"></div>
    <script src="https://unpkg.com/mostage@latest/dist/core/index.js"></script>
    <script>
      //Use internal config or path of external config
      const presentation = new Mostage({
        element: "#app",
        contentPath: "./content.md",
        theme: "dark",
      });
      presentation.start();
    </script>
  </body>
</html>

Create content.md with your content:

# Slide 1

Welcome to my presentation!

---

# Slide 2

This is the second slide.

Create config.json (optional):

{
  "theme": "light",
  "scale": 1.2
}

Option 4: Framework Integration

Mostage works with popular frameworks and build tools:

React

import React, { useEffect, useRef } from "react";
import Mostage from "mostage";

function Presentation() {
  const containerRef = useRef(null);

  useEffect(() => {
    if (containerRef.current) {
      const presentation = new Mostage({
        element: containerRef.current,
        contentPath: "./content.md",
        theme: "dark",
      });
      presentation.start();
    }
  }, []);

  return <div ref={containerRef} />;
}

Angular

import { Component, ElementRef, OnInit, OnDestroy } from "@angular/core";
import Mostage from "mostage";

@Component({
  selector: "app-presentation",
  template: "<div></div>",
})
export class PresentationComponent implements OnInit, OnDestroy {
  private mostage: any;

  constructor(private elementRef: ElementRef) {}

  ngOnInit() {
    this.mostage = new Mostage({
      element: this.elementRef.nativeElement,
      theme: "dark",
      contentPath: "./content.md",
    });
    this.mostage.start();
  }

  ngOnDestroy() {
    if (this.mostage) {
      this.mostage.destroy();
    }
  }
}

Configuration

Mostage is highly configurable through the config.json file. Here are the main configuration options:

Basic Configuration

{
  "theme": "dark",
  "scale": 1.2,
  "urlHash": true
}

Content Configuration

{
  "contentPath": "./content.md",
  "centerContent": {
    "vertical": true,
    "horizontal": true
  }
}

Headers & Footers

{
  "header": {
    "content": "# My Presentation",
    "position": "top-left",
    "showOnFirstSlide": false
  },
  "footer": {
    "content": "#### Presentation Framework",
    "position": "bottom-left",
    "showOnFirstSlide": true
  }
}

Backgrounds

{
  "background": [
    {
      "imagePath": "./background.jpg",
      "size": "cover",
      "position": "center",
      "bgColor": "#000000",
      "global": true
    }
  ]
}

Plugins

{
  "plugins": {
    "ProgressBar": {
      "enabled": true,
      "position": "top",
      "color": "#007acc"
    },
    "SlideNumber": {
      "enabled": true,
      "position": "bottom-right",
      "format": "current/total"
    },
    "Controller": {
      "enabled": true,
      "position": "bottom-center"
    },
    "Confetti": {
      "enabled": true,
      "particleCount": 50
    }
  }
}

Available Themes

light - Clean light theme
dark - Modern dark theme
dracula - Dracula color scheme
ocean - Ocean blue theme
rainbow - Colorful rainbow theme

Built-in Plugins

ProgressBar - Shows presentation progress
SlideNumber - Displays current slide number
Controller - Navigation controls
Confetti - Celebration animations

Configuration Example

For a complete configuration example, see Usage Examples.

Usage Examples

For detailed usage examples and advanced configurations, see Usage Examples.

API Reference

For complete API documentation, see API Reference.

Development

For development guidelines, contribution instructions, and CI/CD pipeline information, see the Development Guide.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0-or-later) with additional attribution requirements.

See the LICENSE file for the complete license text.