docs: documentation fonctionnelle, technique et installation
This commit is contained in:
@@ -0,0 +1,58 @@
|
||||
# Vue d'ensemble
|
||||
|
||||
## Qu'est-ce que Pena ?
|
||||
|
||||
Pena est un **lecteur Markdown de bureau**. Son objectif est d'offrir une lecture confortable
|
||||
de documentation écrite en Markdown, qu'il s'agisse d'un fichier unique (un `README.md`) ou
|
||||
d'un ensemble de fichiers organisés en arborescence (un « wiki » de documentation).
|
||||
|
||||
Contrairement à un éditeur, Pena est **focalisé sur la lecture** : il n'édite pas les fichiers,
|
||||
il les affiche joliment, permet de naviguer entre eux, et de personnaliser entièrement
|
||||
l'apparence du rendu.
|
||||
|
||||
## Pour qui ?
|
||||
|
||||
- Toute personne qui consulte régulièrement de la documentation Markdown en local
|
||||
(wikis de projet, notes, documentation technique).
|
||||
- Les utilisateurs qui veulent un rendu plus agréable et configurable que l'aperçu brut
|
||||
d'un éditeur de texte.
|
||||
- Ceux qui maintiennent une documentation multi-fichiers organisée en dossiers et
|
||||
sous-dossiers, et qui veulent naviguer dedans comme dans un wiki.
|
||||
|
||||
## Deux modes d'ouverture
|
||||
|
||||
Pena propose deux façons d'ouvrir du contenu :
|
||||
|
||||
| Mode | Déclencheur | Comportement |
|
||||
|---|---|---|
|
||||
| **Fichier** | « Ouvrir un fichier Markdown » | Ouvre un `.md` isolé. La barre latérale liste tous les `.md` du dossier parent pour faciliter la navigation. |
|
||||
| **Dossier (wiki)** | « Ouvrir un dossier wiki » | Ouvre un dossier complet. Tous les `.md` (y compris dans les sous-dossiers) sont listés en arborescence. Si un fichier `Home.md` existe, il est affiché en premier. |
|
||||
|
||||
## Principes de fonctionnement
|
||||
|
||||
- **Rendu côté Rust** — La conversion Markdown → HTML est faite par le backend Rust
|
||||
(`comrak`), pas par une bibliothèque JS. Cela garantit un rendu rapide et cohérent.
|
||||
- **CommonMark + extensions** — Les tableaux, le texte barré, les liens automatiques et les
|
||||
listes de tâches sont pris en charge.
|
||||
- **Coloration syntaxique** — Les blocs de code sont colorés via `syntect`, avec un thème
|
||||
de coloration intégré (`base16-ocean.dark`).
|
||||
- **Navigation entre documents** — Les liens Markdown relatifs entre fichiers
|
||||
(ex. `[voir](../autre/page.md)`) sont fonctionnels : cliquer dessus charge le document
|
||||
cible dans Pena.
|
||||
- **Tout reste local** — Aucune connexion réseau n'est nécessaire. Les préférences
|
||||
(récents, thème, CSS personnalisé) sont stockées localement dans le navigateur embarqué
|
||||
(localStorage).
|
||||
|
||||
## Ce que Pena ne fait pas (encore)
|
||||
|
||||
- Pas d'édition de fichiers Markdown (lecture seule).
|
||||
- Pas de rechargement automatique à la modification du fichier : le mécanisme de
|
||||
surveillance (« watcher ») existe côté backend mais n'est pas branché côté interface.
|
||||
Voir [Commandes Tauri](../2-technique/2.2-Commandes-Tauri.md#surveillance-de-fichiers-watch).
|
||||
|
||||
## Voir aussi
|
||||
|
||||
- [Fonctionnalités détaillées](1.2-Fonctionnalites.md)
|
||||
- [Interface](1.3-Interface.md)
|
||||
- [Thèmes et personnalisation](1.4-Themes-et-personnalisation.md)
|
||||
- [Architecture technique](../2-technique/2.1-Architecture.md)
|
||||
@@ -0,0 +1,115 @@
|
||||
# Fonctionnalités
|
||||
|
||||
Cette page liste l'ensemble des fonctionnalités visibles par l'utilisateur, regroupées par
|
||||
thème.
|
||||
|
||||
## 1. Ouverture de documents
|
||||
|
||||
### Ouvrir un fichier Markdown
|
||||
- Bouton **« Ouvrir un fichier Markdown »** sur l'écran d'accueil.
|
||||
- Ouvre un sélecteur de fichiers natif, filtré sur l'extension `.md`.
|
||||
- Une fois le fichier ouvert, la barre latérale liste **tous les `.md` du dossier parent**,
|
||||
ce qui permet de basculer entre fichiers voisins.
|
||||
|
||||
### Ouvrir un dossier wiki
|
||||
- Bouton **« Ouvrir un dossier wiki »** sur l'écran d'accueil.
|
||||
- Ouvre un sélecteur de dossier natif.
|
||||
- Tous les fichiers `.md` du dossier **et de ses sous-dossiers** sont listés (récursivement).
|
||||
- Les fichiers et dossiers cachés (commençant par `.`) sont ignorés.
|
||||
- Si un fichier `Home.md` ou `home.md` est présent à la racine, il est affiché en premier ;
|
||||
sinon, c'est le premier fichier par ordre alphabétique.
|
||||
|
||||
## 2. Documents récents
|
||||
|
||||
- L'écran d'accueil affiche une section **« Récents »** (masquée si vide).
|
||||
- Chaque entrée affiche une icône (📁 pour un dossier, 📄 pour un fichier), le nom et le
|
||||
chemin parent.
|
||||
- Un clic réouvre directement le fichier ou le dossier.
|
||||
- Jusqu'à **8 entrées** sont conservées, sans doublon, dans le stockage local (localStorage,
|
||||
clé `pena_recents`).
|
||||
|
||||
## 3. Navigation dans la documentation
|
||||
|
||||
### Barre latérale en arborescence
|
||||
- Affiche la structure complète du dossier ouvert sous forme d'arbre.
|
||||
- Les dossiers sont des sections repliables/dépliables (chevron).
|
||||
- Fichiers et dossiers sont triés par **ordre naturel** : les préfixes numériques
|
||||
sont comparés comme des nombres (`10` vient après `9`, et non après `1`).
|
||||
- Dossiers et fichiers partagent la **même typographie** (taille et graisse) ;
|
||||
seul le chevron ▶ distingue visuellement un dossier.
|
||||
- Si un dossier contient un `home.md`, son nom devient un lien cliquable.
|
||||
- Le document actuellement affiché est **surligné**, et les dossiers parents sont
|
||||
automatiquement dépliés.
|
||||
- Plusieurs niveaux de profondeur sont gérés avec une indentation progressive.
|
||||
|
||||
### Liens entre documents
|
||||
- Les **liens Markdown relatifs** vers d'autres fichiers `.md`
|
||||
(ex. `[autre page](../section/page.md)`) sont fonctionnels : un clic charge le document
|
||||
cible dans Pena, sans quitter l'application. Les chemins relatifs (`../`, `./`) sont
|
||||
résolus correctement.
|
||||
- Les **liens externes** (`http://`, `https://`) s'ouvrent dans le navigateur par défaut
|
||||
(nouvel onglet, avec `rel="noopener noreferrer"`).
|
||||
- Les **ancres internes** (`#section`) restent des ancres de page.
|
||||
|
||||
## 4. Rendu Markdown
|
||||
|
||||
Le rendu prend en charge le standard **CommonMark** ainsi que les extensions suivantes :
|
||||
|
||||
| Extension | Exemple |
|
||||
|---|---|
|
||||
| Tableaux | `\| col A \| col B \|` |
|
||||
| Texte barré | `~~barré~~` |
|
||||
| Liens automatiques | une URL nue devient un lien cliquable |
|
||||
| Listes de tâches | `- [ ] à faire` / `- [x] fait` |
|
||||
|
||||
Autres éléments rendus : titres `h1`–`h6`, code inline, blocs de code, citations
|
||||
(blockquotes), listes, images (largeur adaptée), et liens.
|
||||
|
||||
## 5. Coloration syntaxique du code
|
||||
|
||||
- Les blocs de code délimités par triple backtick sont **colorés syntaxiquement** via
|
||||
`syntect`.
|
||||
- Le thème de coloration intégré est **`base16-ocean.dark`**.
|
||||
- La syntaxe **TypeScript** est fournie en plus des syntaxes par défaut.
|
||||
|
||||
### Bouton « Copier » sur les blocs de code
|
||||
- Chaque bloc de code affiche un bouton **« Copier »** en haut à droite.
|
||||
- Un clic copie le contenu du bloc dans le presse-papiers.
|
||||
- Un retour visuel temporaire (« Copié ! ») confirme l'action.
|
||||
|
||||
## 6. Personnalisation de l'apparence
|
||||
|
||||
Voir la page dédiée [Thèmes et personnalisation](1.4-Themes-et-personnalisation.md). En résumé :
|
||||
|
||||
- **6 thèmes rapides** prêts à l'emploi (Défaut, Mode sombre, Sépia, Grand texte,
|
||||
Accent émeraude, Shell Indigo).
|
||||
- Un **éditeur CSS** intégré, organisé en 4 onglets thématiques, permettant d'écrire son
|
||||
propre CSS appliqué au rendu.
|
||||
- Les choix sont **persistés** localement et réappliqués au démarrage suivant.
|
||||
|
||||
## 7. Fenêtre et barre de titre personnalisée
|
||||
|
||||
- L'application utilise une **barre de titre maison** (la décoration native est désactivée).
|
||||
- Elle affiche le titre du document courant et propose les boutons **réduire**,
|
||||
**agrandir / restaurer** et **fermer**.
|
||||
- La fenêtre se déplace en glissant la barre de titre.
|
||||
|
||||
## 8. Rechargement automatique (live-reload)
|
||||
|
||||
- À l'ouverture d'un fichier ou d'un dossier, l'application **surveille** en continu son
|
||||
contenu sur le disque.
|
||||
- Quand le **document affiché** est modifié (par un éditeur externe, un `git pull`, etc.),
|
||||
il est **rechargé automatiquement** — plus besoin de revenir à l'accueil et de rouvrir le
|
||||
dossier.
|
||||
- Quand un fichier `.md` est **ajouté ou supprimé** dans le dossier ouvert, la **sidebar**
|
||||
se met à jour automatiquement pour refléter la nouvelle arborescence (le dossier du
|
||||
document courant reste déplié).
|
||||
- La surveillance s'arrête au retour à l'accueil et se réinitialise à chaque nouvelle
|
||||
ouverture. Détails techniques :
|
||||
[Surveillance de fichiers](../2-technique/2.2-Commandes-Tauri.md#surveillance-de-fichiers-watch).
|
||||
|
||||
## Voir aussi
|
||||
|
||||
- [Interface](1.3-Interface.md)
|
||||
- [Thèmes et personnalisation](1.4-Themes-et-personnalisation.md)
|
||||
- [Vue d'ensemble](1.1-Vue-d-ensemble.md)
|
||||
@@ -0,0 +1,77 @@
|
||||
# Interface
|
||||
|
||||
L'interface de Pena se compose de deux vues principales — l'**accueil** et le **lecteur** —
|
||||
surmontées d'une **barre de titre personnalisée** toujours visible.
|
||||
|
||||
## Barre de titre personnalisée
|
||||
|
||||
La décoration native de la fenêtre est désactivée ; Pena fournit sa propre barre de titre
|
||||
en haut de la fenêtre (hauteur 36 px, fond sombre).
|
||||
|
||||
| Élément | Comportement |
|
||||
|---|---|
|
||||
| Titre | Affiche « Pena — Markdown Viewer » sur l'accueil, ou le titre du document ouvert dans le lecteur. |
|
||||
| Zone de titre | Glisser-déposer pour déplacer la fenêtre. |
|
||||
| Bouton **─** | Réduit la fenêtre. |
|
||||
| Bouton **▢** | Agrandit la fenêtre, ou la restaure si elle est déjà agrandie. |
|
||||
| Bouton **✕** | Ferme l'application (devient rouge au survol). |
|
||||
|
||||
## Vue d'accueil
|
||||
|
||||
C'est l'écran affiché au démarrage et quand on revient via « ← Accueil ».
|
||||
|
||||
Elle contient :
|
||||
|
||||
- Le **titre « Pena »** en grand.
|
||||
- Deux boutons d'action :
|
||||
- **« Ouvrir un fichier Markdown »**
|
||||
- **« Ouvrir un dossier wiki »**
|
||||
- Une section **« Récents »** (visible uniquement s'il y a des documents récents) listant les
|
||||
derniers fichiers et dossiers ouverts, cliquables pour les rouvrir.
|
||||
|
||||
## Vue lecteur
|
||||
|
||||
Affichée dès qu'un document est ouvert. Elle est composée de deux zones :
|
||||
|
||||
### Barre latérale (gauche)
|
||||
- Largeur fixe (264 px), fond sombre.
|
||||
- En haut : le **nom du dossier** ouvert.
|
||||
- Au centre : l'**arborescence des fichiers** `.md` (voir
|
||||
[Navigation](1.2-Fonctionnalites.md#3-navigation-dans-la-documentation)).
|
||||
- En bas (pied de barre) : deux boutons —
|
||||
- **« Personnaliser CSS »** (ouvre la modale de thèmes / CSS) ;
|
||||
- **« ← Accueil »** (revient à l'écran d'accueil).
|
||||
|
||||
### Zone de contenu (droite)
|
||||
- Affiche le document Markdown rendu en HTML.
|
||||
- Fond clair, typographie soignée, largeur de lecture limitée pour le confort.
|
||||
- Chaque bloc de code possède un bouton **« Copier »**.
|
||||
|
||||
### Comportement responsive
|
||||
- Sur les fenêtres larges, la barre latérale est visible en permanence à gauche.
|
||||
- Sous ~1020 px de large, la barre latérale se rétracte et le contenu occupe toute la largeur.
|
||||
- Sous ~540 px, les marges du contenu sont réduites.
|
||||
|
||||
## Modale de personnalisation CSS
|
||||
|
||||
Ouverte via le bouton « Personnaliser CSS » de la barre latérale. Voir la page dédiée
|
||||
[Thèmes et personnalisation](1.4-Themes-et-personnalisation.md) pour le détail.
|
||||
|
||||
Elle se ferme via la croix, le bouton « Fermer », ou un clic en dehors de la modale.
|
||||
|
||||
## Palette visuelle
|
||||
|
||||
| Rôle | Usage |
|
||||
|---|---|
|
||||
| Fond sombre | Barre de titre, barre latérale |
|
||||
| Fond clair | Zone de contenu |
|
||||
| Accent rose/corail | Boutons, survols, liens d'action, bordures de tableaux |
|
||||
| Accent indigo | Élément actif dans la barre latérale |
|
||||
|
||||
> L'ensemble de ces couleurs peut être surchargé par l'utilisateur via les thèmes rapides ou
|
||||
> le CSS personnalisé.
|
||||
|
||||
## Voir aussi
|
||||
|
||||
- [Fonctionnalités](1.2-Fonctionnalites.md)
|
||||
- [Thèmes et personnalisation](1.4-Themes-et-personnalisation.md)
|
||||
@@ -0,0 +1,80 @@
|
||||
# Thèmes et personnalisation
|
||||
|
||||
Pena permet de modifier entièrement l'apparence du rendu, via deux mécanismes
|
||||
complémentaires : les **thèmes rapides** (prêts à l'emploi) et l'**éditeur CSS** (sur mesure).
|
||||
Tout se passe dans la **modale « Personnaliser CSS »**, ouverte depuis la barre latérale.
|
||||
|
||||
## Thèmes rapides
|
||||
|
||||
Six thèmes sont fournis et gérés par le backend. Chacun est un fichier CSS intégré à
|
||||
l'application.
|
||||
|
||||
| Identifiant | Libellé affiché |
|
||||
|---|---|
|
||||
| `default` | Défaut |
|
||||
| `dark` | Mode sombre |
|
||||
| `sepia` | Sépia |
|
||||
| `large-text` | Grand texte |
|
||||
| `emerald` | Accent émeraude |
|
||||
| `shell-indigo` | Shell Indigo |
|
||||
|
||||
### Utilisation
|
||||
- Les thèmes apparaissent sous forme de **badges cliquables** dans la modale.
|
||||
- Un clic applique le thème **immédiatement**.
|
||||
- Le badge du thème actif est mis en évidence.
|
||||
- Cliquer à nouveau sur le thème actif le **désactive** (retour au rendu de base).
|
||||
- Le thème choisi est mémorisé (localStorage, clé `pena_quick_theme`) et réappliqué au
|
||||
prochain démarrage.
|
||||
|
||||
## Éditeur CSS personnalisé
|
||||
|
||||
Pour aller plus loin qu'un thème, la modale propose un éditeur de CSS libre, organisé en
|
||||
**4 onglets** thématiques. Chaque onglet conserve son propre CSS, indépendamment des autres :
|
||||
|
||||
| Onglet | Vocation |
|
||||
|---|---|
|
||||
| Arrière-scène | Styles généraux / d'ambiance |
|
||||
| Police | Typographie |
|
||||
| Contenu fond | Mise en forme du contenu |
|
||||
| Développement | Réglages avancés / divers |
|
||||
|
||||
### Fonctionnement
|
||||
- On écrit du **CSS standard** dans la zone de texte de l'onglet sélectionné.
|
||||
- Le bouton **« ★ Enregistrer »** sauvegarde le CSS courant et l'applique aussitôt.
|
||||
- Le bouton **« Réinitialiser »** efface **tout** le CSS personnalisé **et** désactive le
|
||||
thème rapide actif.
|
||||
- Le bouton **« Fermer »** ferme la modale sans enregistrer les changements en cours.
|
||||
- Un champ permet de nommer la configuration.
|
||||
|
||||
### Application combinée
|
||||
Le CSS finalement appliqué est la **concaténation** du CSS des 4 onglets, suivi du CSS du
|
||||
thème rapide actif. L'ordre de cascade est donc :
|
||||
|
||||
1. CSS de base de l'application (`style.css`) ;
|
||||
2. CSS personnalisé (les 4 onglets, concaténés) ;
|
||||
3. CSS du thème rapide actif (s'il y en a un).
|
||||
|
||||
Ainsi, un thème rapide peut compléter un CSS personnalisé, et le CSS personnalisé peut
|
||||
surcharger le rendu de base.
|
||||
|
||||
## Persistance des préférences
|
||||
|
||||
Toutes les préférences sont stockées localement (localStorage) et restaurées à chaque
|
||||
ouverture :
|
||||
|
||||
| Donnée | Clé localStorage |
|
||||
|---|---|
|
||||
| Thème rapide actif | `pena_quick_theme` |
|
||||
| CSS onglet « Arrière-scène » | `pena_css_general` |
|
||||
| CSS onglet « Police » | `pena_css_police` |
|
||||
| CSS onglet « Contenu fond » | `pena_css_contenu` |
|
||||
| CSS onglet « Développement » | `pena_css_avance` |
|
||||
|
||||
> Ces données sont propres à la machine et à l'installation : elles ne sont pas synchronisées
|
||||
> et ne quittent jamais l'ordinateur.
|
||||
|
||||
## Voir aussi
|
||||
|
||||
- [Interface](1.3-Interface.md)
|
||||
- [Fonctionnalités](1.2-Fonctionnalites.md)
|
||||
- [Commandes Tauri — Thèmes](../2-technique/2.2-Commandes-Tauri.md#thèmes)
|
||||
Reference in New Issue
Block a user