Guida Introduttiva

Il percorso: Installa → Crea Progetto → Scrivi → Anteprima → Commit

Installazione

MdExplorer è disponibile per Windows e Linux. L'installazione è semplice e veloce su entrambe le piattaforme.

Windows

Su Windows, MdExplorer utilizza un bootstrapper installer leggero (circa 3 MB). L'installer scarica automaticamente tutti i componenti necessari e configura l'applicazione. Una volta installato, MdExplorer include un sistema di aggiornamento automatico integrato: ad ogni avvio l'applicazione verifica la disponibilità di nuove versioni e si aggiorna in modo trasparente, senza richiedere intervento manuale.

1. Scarica il bootstrapper installer dalla pagina di download.
2. Esegui il file mdexplorer-bootstrapper-setup.exe e segui le istruzioni a schermo.
3. Al termine dell'installazione, MdExplorer si avvia automaticamente ed è pronto all'uso.

Linux

Su Linux, MdExplorer è distribuito come AppImage, un formato portatile che non richiede installazione nel sistema. Basta scaricare il file, renderlo eseguibile e avviarlo.

1. Scarica il file .AppImage dalla pagina di download.
2. Rendi il file eseguibile con il comando: chmod +x mdexplorer-*.AppImage
3. Avvia l'applicazione con un doppio click oppure da terminale: ./mdexplorer-*.AppImage

Requisiti opzionali

The path: Install → Create Project → Write → Preview → Commit

Installation

MdExplorer is available for Windows and Linux. Installation is quick and straightforward on both platforms.

Windows

On Windows, MdExplorer uses a lightweight bootstrapper installer (approximately 3 MB). The installer automatically downloads all required components and configures the application. Once installed, MdExplorer includes a built-in auto-update system: on every launch the application checks for new versions and updates transparently, with no manual intervention required.

1. Download the bootstrapper installer from the download page.
2. Run the mdexplorer-bootstrapper-setup.exe file and follow the on-screen instructions.
3. When installation completes, MdExplorer launches automatically and is ready to use.

Linux

On Linux, MdExplorer is distributed as an AppImage, a portable format that requires no system-level installation. Simply download the file, make it executable, and run it.

1. Download the .AppImage file from the download page.
2. Make the file executable by running: chmod +x mdexplorer-*.AppImage
3. Launch the application with a double click or from the terminal: ./mdexplorer-*.AppImage

Optional Requirements

Crea il Primo Progetto

Un progetto in MdExplorer corrisponde a una cartella sul file system che contiene i tuoi file Markdown. Quando apri una cartella come progetto, MdExplorer crea automaticamente la struttura necessaria per gestire template, impostazioni e metadati.

1. Apri MdExplorer e nella schermata iniziale clicca sul pulsante "Apri Cartella" (oppure usa la scorciatoia dalla toolbar).
2. Seleziona la cartella che vuoi usare come progetto. Può essere una cartella vuota oppure una cartella che contiene già file .md.
3. Struttura automatica: MdExplorer crea una sotto-cartella .md/ all'interno del tuo progetto. Questa cartella è nascosta e contiene tutto il necessario per il funzionamento dell'applicazione.
4. Indicizzazione: Tutti i file Markdown presenti nella cartella vengono indicizzati automaticamente e visualizzati nella tree view laterale. Puoi iniziare subito a navigare e modificare i tuoi documenti.

Cosa contiene la cartella .md/

La cartella .md/ viene creata alla radice del progetto e contiene:

• templates/pdf/ — Template LaTeX (Eisvogel) per l'export in PDF. Puoi personalizzare l'aspetto dei documenti esportati modificando questi file.
• templates/word/ — Template Word (reference.docx, minute.docx) utilizzati come base per l'export in formato Word.
• MdProject_{hash}.db — Database SQLite del progetto che memorizza impostazioni specifiche, metadati dei file e informazioni sulla struttura del progetto.

Create Your First Project

A project in MdExplorer corresponds to a folder on the file system that contains your Markdown files. When you open a folder as a project, MdExplorer automatically creates the structure needed to manage templates, settings, and metadata.

1. Open MdExplorer and on the start screen click the "Open Folder" button (or use the toolbar shortcut).
2. Select the folder you want to use as a project. It can be an empty folder or one that already contains .md files.
3. Automatic structure: MdExplorer creates a .md/ subfolder inside your project. This hidden folder contains everything the application needs to function.
4. Indexing: All Markdown files in the folder are automatically indexed and displayed in the side tree view. You can immediately start navigating and editing your documents.

What the .md/ folder contains

The .md/ folder is created at the project root and contains:

• templates/pdf/ — LaTeX templates (Eisvogel) for PDF export. You can customize the appearance of exported documents by editing these files.
• templates/word/ — Word templates (reference.docx, minute.docx) used as the base for Word format export.
• MdProject_{hash}.db — Project SQLite database storing project-specific settings, file metadata, and project structure information.

Scrivi il Primo File Markdown

Una volta creato il progetto, sei pronto per scrivere il tuo primo documento. MdExplorer utilizza Milkdown, un editor WYSIWYG basato su Markdown che ti permette di scrivere in modo visuale mantenendo il formato Markdown puro nel file salvato.

Crea un nuovo file

Dalla tree view laterale, clicca con il tasto destro sulla cartella dove vuoi creare il file e seleziona "Nuovo File". Assegna un nome con estensione .md (ad esempio requisiti.md) e il file si apre automaticamente nell'editor.

L'editor Milkdown

L'editor offre una toolbar con le operazioni di formattazione più comuni e supporta le scorciatoie da tastiera standard:

• Heading — Usa # Titolo per gli heading di livello 1, ## Titolo per il livello 2, e così via. Oppure seleziona il testo e usa la toolbar.
• Grassetto — Seleziona il testo e premi Ctrl+B oppure racchiudilo tra **doppi asterischi**.
• Corsivo — Seleziona il testo e premi Ctrl+I oppure racchiudilo tra *asterischi singoli*.
• Link — Usa la sintassi [testo del link](url) oppure il pulsante nella toolbar. I link ad altri file .md del progetto vengono riconosciuti e indicizzati automaticamente.
• Codice — Usa `backtick singoli` per il codice inline, oppure ```triple backtick``` per blocchi di codice con syntax highlighting.
• Liste — Usa - o * per liste puntate, 1. per liste numerate. Le liste supportano annidamento con indentazione.

Write Your First Markdown File

Once your project is created, you are ready to write your first document. MdExplorer uses Milkdown, a WYSIWYG editor built on Markdown that lets you write visually while keeping pure Markdown format in the saved file.

Create a new file

From the side tree view, right-click on the folder where you want to create the file and select "New File". Give it a name with the .md extension (e.g. requirements.md) and the file automatically opens in the editor.

The Milkdown editor

The editor provides a toolbar with the most common formatting operations and supports standard keyboard shortcuts:

• Headings — Use # Title for level 1 headings, ## Title for level 2, and so on. Or select text and use the toolbar.
• Bold — Select text and press Ctrl+B or wrap it with **double asterisks**.
• Italic — Select text and press Ctrl+I or wrap it with *single asterisks*.
• Links — Use the syntax [link text](url) or the toolbar button. Links to other .md files in the project are automatically recognized and indexed.
• Code — Use `single backticks` for inline code, or ```triple backticks``` for code blocks with syntax highlighting.
• Lists — Use - or * for bullet lists, 1. for numbered lists. Lists support nesting with indentation.

Anteprima Documento

MdExplorer offre un'anteprima in tempo reale del tuo documento Markdown renderizzato. Mentre scrivi, puoi vedere immediatamente come apparirà il risultato finale, inclusi heading, tabelle, immagini, blocchi di codice e diagrammi PlantUML.

Modalità Split-View

La modalità split-view divide lo schermo in due pannelli affiancati: a sinistra l'editor dove scrivi, a destra l'anteprima renderizzata. Questa modalità è ideale durante la scrittura perché ti permette di vedere in tempo reale l'effetto delle modifiche senza interrompere il flusso di lavoro. Lo scrolling è sincronizzato tra i due pannelli per mantenere sempre visibile la sezione su cui stai lavorando.

Preview a Schermo Intero

La modalità preview a schermo intero nasconde l'editor e mostra il documento renderizzato su tutta la larghezza disponibile. Questa modalità è utile per la rilettura del documento, per le presentazioni o per verificare il layout finale prima dell'esportazione. Il documento viene visualizzato con la stessa formattazione che avrà nell'export PDF o Word.

Document Preview

MdExplorer provides a real-time preview of your rendered Markdown document. As you write, you can immediately see how the final result will look, including headings, tables, images, code blocks, and PlantUML diagrams.

Split-View Mode

The split-view mode divides the screen into two side-by-side panels: the editor on the left where you write, and the rendered preview on the right. This mode is ideal during writing because it allows you to see the effect of changes in real time without interrupting your workflow. Scrolling is synchronized between both panels to always keep the section you are working on visible.

Full-Screen Preview

The full-screen preview mode hides the editor and displays the rendered document at full width. This mode is useful for proofreading the document, for presentations, or for checking the final layout before exporting. The document is displayed with the same formatting it will have in PDF or Word export.

Primo Commit con Git

MdExplorer include un pannello Git integrato che ti permette di gestire il versionamento dei tuoi documenti direttamente dall'applicazione, senza dover aprire un terminale o un client Git esterno.

1. Apri il pannello Git cliccando sull'icona Git nella sidebar laterale. Il pannello mostra lo stato corrente del repository: file modificati, file nuovi e file eliminati.
2. Controlla i file modificati: La lista mostra tutti i file che sono stati modificati dall'ultimo commit. Puoi cliccare su ciascun file per vedere il diff delle modifiche, con evidenziazione delle righe aggiunte e rimosse.
3. Scrivi il messaggio di commit: Nel campo di testo in alto, scrivi un messaggio descrittivo per il commit. Un buon messaggio descrive brevemente cosa è stato cambiato e perché (ad esempio: "Aggiunta sezione requisiti funzionali alla SRS").
4. Clicca Commit: Premi il pulsante Commit per salvare le modifiche nel repository locale. MdExplorer esegue un git add dei file selezionati seguito dal git commit con il messaggio specificato.

Dopo il commit, puoi continuare a lavorare sui tuoi documenti. I commit successivi tracciano l'evoluzione delle tue specifiche nel tempo, permettendoti di tornare a versioni precedenti quando necessario e di collaborare con il team attraverso branch e merge.

First Git Commit

MdExplorer includes a built-in Git panel that lets you manage version control for your documents directly from the application, without needing to open a terminal or an external Git client.

1. Open the Git panel by clicking the Git icon in the sidebar. The panel shows the current repository status: modified files, new files, and deleted files.
2. Review changed files: The list shows all files that have been modified since the last commit. You can click on each file to see the diff of changes, with added and removed lines highlighted.
3. Write the commit message: In the text field at the top, write a descriptive commit message. A good message briefly describes what was changed and why (for example: "Added functional requirements section to SRS").
4. Click Commit: Press the Commit button to save changes to the local repository. MdExplorer performs a git add of the selected files followed by a git commit with the specified message.

After the commit, you can continue working on your documents. Subsequent commits track the evolution of your specifications over time, allowing you to return to previous versions when needed and collaborate with the team through branches and merges.