App Esterne

Ospita qualsiasi applicazione nel pannello documenti di MdExplorer

Cos'è l'External App Embedding?

MdExplorer permette di ospitare applicazioni esterne direttamente nel pannello destro, accanto all'alberatura dei file. Ogni applicazione appare come un nodo speciale nel tree con un'icona configurabile: un clic la avvia e la mostra; navigando su un documento .md l'app si nasconde ma rimane in esecuzione, pronta a tornare visibile senza un nuovo avvio.

Caso d'uso tipico: uno strumento di monitoring, una dashboard di progetto, un editor specializzato o qualsiasi tool Web — tutto senza uscire da MdExplorer.

Configurazione: `.mdeapps.json`

Crea un file .mdeapps.json nella root del tuo progetto MdE:

{
  "version": "1",
  "apps": [
    {
      "id": "my-dashboard",
      "name": "Dashboard",
      "description": "Pannello di controllo del progetto",
      "icon": "dashboard",
      "executable": ".mde/apps/dashboard.exe",
      "args": [],
      "treePosition": "bottom",
      "singleton": true
    }
  ]
}

Campi disponibili

Campo	Tipo	Obbligatorio	Descrizione
`id`	string	✓	Identificatore univoco (niente spazi)
`name`	string	✓	Nome visualizzato nel tree
`executable`	string	✓	Path assoluto o relativo alla root del progetto
`args`	string[]		Argomenti extra da passare all'eseguibile
`icon`	string		Nome icona Material Icons (default: `launch`)
`description`	string		Tooltip mostrato passando il mouse sul nodo
`treePosition`	`"top"` \| `"bottom"`		Posizione nel tree (default: `"bottom"`)
`singleton`	boolean		Se `true`, riusa il processo già avviato (default: `true`)

Path relativi: "executable": ".mde/apps/myapp.exe" viene risolto come <ProjectRoot>/.mde/apps/myapp.exe. Consigliato per distribuire le app assieme al progetto.

Come sviluppare un'app esterna

Un'app esterna deve implementare un semplice protocollo HTTP. MdExplorer passa automaticamente gli argomenti necessari all'avvio:

myapp.exe --mde-embedded --port 54321 --mde-host http://localhost:48123

Cosa deve fare l'app

Rilevare il flag --mde-embedded — se presente, non aprire finestre proprie
Avviare un HTTP server sulla porta indicata da --port
Rispondere 200 OK a GET / con l'HTML dell'interfaccia
Terminare pulitamente quando il processo riceve un segnale di kill

Esempio Node.js

// server.js
const http = require('http');
const args = process.argv.slice(2);
const port = parseInt(args[args.indexOf('--port') + 1]);

http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
  res.end('<h1>La mia app</h1>');
}).listen(port, '127.0.0.1', () => {
  console.log(`Avviato su porta ${port}`);
});

Esempio Electron

// main.js
const { app, BrowserWindow } = require('electron');
const http = require('http');

const args = process.argv.slice(2);
const isMdeEmbedded = args.includes('--mde-embedded');
const port = isMdeEmbedded
  ? parseInt(args[args.indexOf('--port') + 1])
  : 3000;

app.whenReady().then(() => {
  if (isMdeEmbedded) {
    // Modalità embedded: solo HTTP server, nessuna finestra
    startHttpServer(port);
  } else {
    // Modalità standalone: finestra normale
    const win = new BrowserWindow({ width: 1200, height: 800 });
    win.loadFile('index.html');
  }
});

function startHttpServer(port) {
  http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end('<h1>La mia app embedded</h1>');
  }).listen(port, '127.0.0.1');
}

Doppia modalità: la stessa app può funzionare sia come tool standalone (con la propria finestra) che embedded in MdExplorer — basta controllare il flag --mde-embedded.

Gestione tramite Settings di Progetto

Le app esterne possono essere aggiunte anche dalla UI di MdExplorer, senza modificare manualmente il file JSON:

Apri le impostazioni del progetto (tasto destro su un file → Document Settings)
Scorri fino alla sezione "App Esterne"
Clicca "Add App" e compila il form
Usa il pulsante "Browse..." per selezionare l'eseguibile dal filesystem
Salva: il tree si aggiorna automaticamente

Lifecycle dell'app

Evento	Comportamento
Clic sul nodo nel tree	MdE avvia il processo e fa polling su `GET /` (max 10 secondi)
App pronta (risponde 200)	La UI dell'app appare nel pannello destro
Navigazione a un documento .md	L'app si nasconde ma il processo rimane vivo
Ritorno al nodo dell'app	L'app torna visibile istantaneamente, senza un nuovo avvio
Quit di MdExplorer	Tutti i processi delle app esterne vengono terminati

Icone Material disponibili

Il campo icon accetta qualsiasi nome di Google Material Icons. Alcuni esempi utili:

dashboard · code · science · terminal · analytics · build · cloud · extension · launch · memory · settings · speed · storage

What is External App Embedding?

MdExplorer lets you host external applications directly in the right panel, alongside the file tree. Each application appears as a special node in the tree with a configurable icon: a single click launches and displays it; navigating to a .md document hides the app but keeps it running, ready to reappear instantly without restarting.

Typical use cases: monitoring tools, project dashboards, specialised editors, or any Web-based tool — all without leaving MdExplorer.

Configuration: `.mdeapps.json`

Create a .mdeapps.json file in the root of your MdE project:

{
  "version": "1",
  "apps": [
    {
      "id": "my-dashboard",
      "name": "Dashboard",
      "description": "Project control panel",
      "icon": "dashboard",
      "executable": ".mde/apps/dashboard.exe",
      "args": [],
      "treePosition": "bottom",
      "singleton": true
    }
  ]
}

Available fields

Field	Type	Required	Description
`id`	string	✓	Unique identifier (no spaces)
`name`	string	✓	Name shown in the tree
`executable`	string	✓	Absolute path or relative to the project root
`args`	string[]		Extra arguments to pass to the executable
`icon`	string		Material Icons name (default: `launch`)
`description`	string		Tooltip shown on hover in the tree
`treePosition`	`"top"` \| `"bottom"`		Position in tree (default: `"bottom"`)
`singleton`	boolean		If `true`, reuses the running process (default: `true`)

Relative paths: "executable": ".mde/apps/myapp.exe" resolves to <ProjectRoot>/.mde/apps/myapp.exe. Recommended for distributing apps together with the project.

How to develop an external app

An external app must implement a simple HTTP protocol. MdExplorer automatically passes the required arguments on launch:

myapp.exe --mde-embedded --port 54321 --mde-host http://localhost:48123

What the app must do

Detect the --mde-embedded flag — if present, do not open any windows
Start an HTTP server on the port given by --port
Return 200 OK on GET / with the interface HTML
Shut down cleanly when the process receives a kill signal

Node.js example

// server.js
const http = require('http');
const args = process.argv.slice(2);
const port = parseInt(args[args.indexOf('--port') + 1]);

http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
  res.end('<h1>My app</h1>');
}).listen(port, '127.0.0.1', () => {
  console.log(`Listening on port ${port}`);
});

Electron example

// main.js
const { app, BrowserWindow } = require('electron');
const http = require('http');

const args = process.argv.slice(2);
const isMdeEmbedded = args.includes('--mde-embedded');
const port = isMdeEmbedded
  ? parseInt(args[args.indexOf('--port') + 1])
  : 3000;

app.whenReady().then(() => {
  if (isMdeEmbedded) {
    // Embedded mode: HTTP server only, no window
    startHttpServer(port);
  } else {
    // Standalone mode: normal window
    const win = new BrowserWindow({ width: 1200, height: 800 });
    win.loadFile('index.html');
  }
});

function startHttpServer(port) {
  http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end('<h1>My embedded app</h1>');
  }).listen(port, '127.0.0.1');
}

Dual mode: the same app can work both as a standalone tool (with its own window) and embedded in MdExplorer — just check the --mde-embedded flag.

Managing apps via Project Settings

External apps can also be added through the MdExplorer UI, without editing the JSON file manually:

Open Project Settings (right-click a file → Document Settings)
Scroll to the "External Apps" section
Click "Add App" and fill in the form
Use the "Browse..." button to pick the executable from the filesystem
Save: the tree updates automatically

App lifecycle

Event	Behaviour
Click on tree node	MdE spawns the process and polls `GET /` (max 10 seconds)
App ready (returns 200)	The app UI appears in the right panel
Navigate to a .md document	App is hidden but the process stays alive
Return to the app node	App reappears instantly, no restart needed
MdExplorer quit	All external app processes are terminated

Available Material Icons

The icon field accepts any Google Material Icons name. Some useful examples:

dashboard · code · science · terminal · analytics · build · cloud · extension · launch · memory · settings · speed · storage

Next Steps

Getting Started

Install MdExplorer and create your first project.

Git Integration

Version control your projects directly from MdExplorer.

PlantUML & Diagrams

Create diagrams directly inside your Markdown documents.

App Esterne

Cos'è l'External App Embedding?

Configurazione: .mdeapps.json

Campi disponibili

Come sviluppare un'app esterna

Cosa deve fare l'app

Esempio Node.js

Esempio Electron

Gestione tramite Settings di Progetto

Lifecycle dell'app

Icone Material disponibili

What is External App Embedding?

Configuration: .mdeapps.json

Available fields

How to develop an external app

What the app must do

Node.js example

Electron example

Managing apps via Project Settings

App lifecycle

Available Material Icons

Next Steps

Configurazione: `.mdeapps.json`

Configuration: `.mdeapps.json`