Rewrite user docs, trim developer-only _docs pages, add python-multipart
This commit is contained in:
brutsalvadi
@@ -0,0 +1,102 @@
|
||||
---
|
||||
title: Content location and structure
|
||||
---
|
||||
|
||||
# Content location and structure
|
||||
|
||||
Two open design questions about where wiki content lives and how it can be
|
||||
organised on disk.
|
||||
|
||||
---
|
||||
|
||||
## Q1 — Content in `site/` vs `bincio_wiki/`
|
||||
|
||||
### The tension
|
||||
|
||||
Ideally wiki content (the `.md` files the community edits) would live in
|
||||
`bincio_wiki/`, the container repo. The Astro app is a reusable engine;
|
||||
content is wiki-specific. Mixing them means content commits go into the
|
||||
`astro-bloomz` submodule history, and updating the engine requires care not
|
||||
to disturb content.
|
||||
|
||||
Currently content is at `site/src/content/entries/` (inside the submodule).
|
||||
|
||||
### Why symlinks failed
|
||||
|
||||
Symlinking `bincio_wiki/pages/` → `site/src/content/entries/` was tried but
|
||||
abandoned: macOS's fsevents (used by Vite's file watcher) does not follow
|
||||
symlinks reliably, causing Astro's hot-reload and content layer to miss
|
||||
changes or crash.
|
||||
|
||||
### Options
|
||||
|
||||
**Option A — Astro glob `base` pointing outside `site/`**
|
||||
|
||||
Change `content.config.ts` to use a relative or absolute path that escapes
|
||||
the `site/` directory:
|
||||
|
||||
```ts
|
||||
loader: glob({ pattern: '**/*.md', base: '../pages' })
|
||||
```
|
||||
|
||||
`../pages` from the Astro project root (`site/`) resolves to
|
||||
`bincio_wiki/pages/`. No symlinks. Content stays in the container repo.
|
||||
|
||||
Risk: Vite (which Astro uses internally) may refuse to watch files outside
|
||||
the project root by default. This can be overridden with
|
||||
`server.watch.ignored` / `server.fs.allow` in `astro.config.mjs`, but needs
|
||||
testing. Build-time collection (no watch) is likely fine regardless.
|
||||
|
||||
**Option B — Copy/sync at dev time**
|
||||
|
||||
Keep content source at `bincio_wiki/pages/` (source of truth). Add a step to
|
||||
`dev.sh` that watches `pages/` and syncs changes to
|
||||
`site/src/content/entries/` (gitignored there). Build step copies before
|
||||
`astro build`.
|
||||
|
||||
Edit server already reads `WIKI_PAGES_DIR` from the environment, so pointing
|
||||
it at `bincio_wiki/pages/` is a one-line change. The sync is the only new
|
||||
piece.
|
||||
|
||||
Downside: a two-directory sync is extra moving parts; a crash or missed sync
|
||||
during dev means stale content in the browser.
|
||||
|
||||
**Option C — Absorb Astro app into `bincio_wiki`**
|
||||
|
||||
Remove the submodule entirely. Move Astro source into `bincio_wiki/src/`.
|
||||
Content and engine live together, content at `src/content/entries/`.
|
||||
|
||||
Cleanest at runtime, but loses `astro-bloomz` as a reusable starting point
|
||||
for other sites. Only worth it if we never intend to fork the engine again.
|
||||
|
||||
### Recommendation
|
||||
|
||||
Try **Option A** first — it is a two-line change and, if Vite's file watcher
|
||||
cooperates, gives us exactly the right separation with minimal risk. If the
|
||||
watcher proves problematic in dev, fall back to **Option B**.
|
||||
|
||||
---
|
||||
|
||||
## Q2 — Subdirectory support in the edit panel
|
||||
|
||||
### Current state
|
||||
|
||||
The backend already handles subdirectory slugs fully:
|
||||
- `_SAFE_SLUG` regex allows `/` in slugs
|
||||
- Routes use `{slug:path}` so FastAPI preserves slashes
|
||||
- `_list()` uses `rglob("*.md")` — nested files are already listed
|
||||
- `_save()` calls `path.parent.mkdir(parents=True, exist_ok=True)`
|
||||
|
||||
The frontend edit panel, however, only offers flat slug input. Work needed:
|
||||
- Allow the "new page" field to accept a slug with `/` (e.g. `archivio/2024/festa`)
|
||||
- Show nested entries grouped by prefix in the page list
|
||||
- Possibly add a folder picker or breadcrumb
|
||||
|
||||
### Pictures
|
||||
|
||||
Not yet addressed. Open questions:
|
||||
- Where are images stored? (options: `site/public/img/`, alongside content,
|
||||
or a dedicated `bincio_wiki/assets/` tree)
|
||||
- How does the edit panel upload/reference them?
|
||||
- How are they referenced from markdown (`/img/foo.jpg` vs relative `./foo.jpg`)?
|
||||
- Are images versioned in git or stored out-of-band?
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
title: Astro-Bloomz
|
||||
date: '2023-10-04'
|
||||
---
|
||||
|
||||
Astro-Bloomz è un [[digital-garden]], la cui caratteristica principale sono i [[wikirefs]] (detti anche "link bidirezionali"). Si tratta di link che usano la sintassi `[[doppia-parentesi-quadra]]` per collegare file all'interno di una collezione di documenti markdown. Possono essere usati in qualsiasi file markdown del sito, a patto che i nomi dei file siano univoci.
|
||||
|
||||
I "Bloomz" sono le parti di un giardino digitale in stile [[wikibonsai]] pensate per essere condivise, mostrate e incrociate — ma attento a non farti pungere! 🐝
|
||||
|
||||
I giardini in stile [[wikibonsai]] aggiungono in particolare un [[semantic-tree]], visualizzabile come una sorta di albero di #tag chiamato [mappa](/map). È costruito a partire dai [[index-type|file indice]], il cui contenuto ne definisce la struttura tramite liste markdown e `[[wikirefs]]`. I file collegati nell'albero semantico sono principalmente [[entry-type|entry]], che fungono da riepiloghi concettuali, in modo simile a una pagina di Wikipedia. Ogni entry mostra anche i riferimenti a ritroso, ovvero quali altri post la citano.
|
||||
|
||||
Queste sintassi e questo modo di lavorare mirano a rendere grandi quantità di contenuti più facilmente navigabili, senza dover ricorrere ad algoritmi e meccanismi di ricerca opachi (anche se questi sono generalmente disponibili).
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
title: 🪴 Digital Garden
|
||||
date: '2021-08-04'
|
||||
---
|
||||
|
||||
La caratteristica distintiva di un [digital garden](https://twitter.com/wibomd/status/1703946098589548622) è il `[[wikiref]]` (o "[[wikirefs|link bidirezionale]]"). Aggiungendo una fitta rete di link interni, le pagine di un sito diventano descrittive di una topografia di concetti che le descrivono o ne vengono utilizzati.
|
||||
|
||||
Le tecniche osservate in natura sono tipicamente un mix derivato da [personal knowledge management](https://en.wikipedia.org/wiki/Personal_knowledge_management), [personal wiki](https://en.wikipedia.org/wiki/Personal_wiki), [tools for thought](https://numinous.productions/ttft/), [zettelkasten](https://en.wikipedia.org/wiki/Zettelkasten) ed [evergreen notes](https://entries.andymatuschak.org/z4SDCZQeRo4xFEQ8H4qrSqd68ucpgE6LU155C), tra gli altri.
|
||||
|
||||
_[[wikibonsai|WikiBonsai]]_ è la sintesi e la cura di ciò che questo particolare giardiniere ha imparato e costruito.
|
||||
|
||||
Curiosità: "giardinaggio" è una metafora sorprendentemente comune che [spunta](https://twitter.com/wibomd/status/1704147337738654189) nei posti più inaspettati.
|
||||
@@ -1,9 +0,0 @@
|
||||
---
|
||||
title: Tipo di Documento
|
||||
---
|
||||
|
||||
I tipi di documento, o "doctype", sono sinonimi delle [content collection di Astro](https://docs.astro.build/en/guides/content-collections/). Sono tipi di documenti markdown usati per renderizzare i contenuti in modi specifici. I seguenti sono i doctype previsti in un [[digital-garden]] stile [[wikibonsai]]:
|
||||
|
||||
- [`posts`](https://docs.astro.build/en/guides/cms/keystatic/#creating-a-new-post)
|
||||
- [[index-type]]
|
||||
- [[entry-type]]
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
title: DocType Entry
|
||||
---
|
||||
|
||||
Come in un dizionario, un'enciclopedia o Wikipedia, le entry sono uno dei tipi di documento centrali di questo template (insieme agli [[index-type]] e ai [[post-type]]). Sono concetti e idee atomici, significativamente [[wikirefs|collegati]] tra loro in modo da rendere comprensibile come quei concetti si relazionano.
|
||||
|
||||
Il percorso breadcrumb è formato dalla posizione dell'entry corrente nell'[[semantic-tree]]. I link nel footer sono costruiti sia dalla sua posizione nell'albero sia dai [[wikirefs]] in avanti e a ritroso.
|
||||
|
||||
### Markdown
|
||||
|
||||
Le entry conterranno tipicamente frontmatter e/o wikiattr, seguiti dal testo markdown:
|
||||
|
||||
```markdown
|
||||
---
|
||||
frontmatter: attributi
|
||||
---
|
||||
|
||||
:tipo::[[wikiattr]]
|
||||
|
||||
Segue il resto del testo del documento,
|
||||
che potrà contenere altri [[wikilink]].
|
||||
```
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
title: DocType Index
|
||||
---
|
||||
|
||||
I documenti indice sono il metodo principale per strutturare l'[[semantic-tree]]. Sono uno dei tipi di documento centrali di questo template (insieme agli [[entry-type]] e ai [[post-type]]).
|
||||
|
||||
### Navigazione
|
||||
|
||||
- Tramite la [[map-page]].
|
||||
- Tramite i [[wikirefs]].
|
||||
|
||||
### Markdown
|
||||
|
||||
I file indice costruiscono l'[[semantic-tree]], visualizzabile nella [[map-page]]. Vanno collocati nella directory `./content/index/` e ciascuno deve contenere un elenco markdown con [[wikirefs]] che puntano tipicamente a [[entry-type|entry]] (ma possono puntare a qualsiasi [[doctype]]). Possono contenere o meno frontmatter yaml.
|
||||
|
||||
I documenti devono avere questa forma (senza i commenti):
|
||||
|
||||
(i caratteri di escape `\\` sono aggiunti per mostrare il testo grezzo)
|
||||
|
||||
```markdown
|
||||
// file: i.bonsai.md
|
||||
|
||||
- [[bk.how-to-read-a-book]]
|
||||
- [[read]]
|
||||
- [[4-levels-of-reading]]
|
||||
- [[elementary-reading]]
|
||||
- [[inspectional-reading]]
|
||||
- [[analytical-reading]]
|
||||
- [[syntopical-reading]]
|
||||
```
|
||||
|
||||
L'albero può essere suddiviso in più file indice:
|
||||
|
||||
```markdown
|
||||
// file: i.bonsai.md
|
||||
|
||||
- [[bk.how-to-read-a-book]]
|
||||
- [[i.read]]
|
||||
```
|
||||
|
||||
```markdown
|
||||
// file: i.read.md
|
||||
|
||||
- [[4-levels-of-reading]]
|
||||
- [[elementary-reading]]
|
||||
- [[inspectional-reading]]
|
||||
- [[analytical-reading]]
|
||||
- [[syntopical-reading]]
|
||||
```
|
||||
|
||||
Entrambi gli esempi genereranno un albero con questa struttura:
|
||||
|
||||
```markdown
|
||||
i.bonsai
|
||||
└── bk.how-to-read-a-book
|
||||
└── i.read
|
||||
└── 4-levels-of-reading
|
||||
├── elementary-reading
|
||||
├── inspectional-reading
|
||||
├── analytical-reading
|
||||
└── syntopical-reading
|
||||
```
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
title: Pagina Mappa
|
||||
---
|
||||
|
||||
Questa pagina mostra l'[[semantic-tree]] completo generato dai documenti [[index-type]].
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Guida rapida al markdown
|
||||
---
|
||||
|
||||
Markdown è il formato di testo usato per scrivere le pagine. Basta qualche simbolo per formattare il testo.
|
||||
|
||||
## Titoli
|
||||
|
||||
```
|
||||
## Titolo grande
|
||||
### Titolo medio
|
||||
#### Titolo piccolo
|
||||
```
|
||||
|
||||
## Grassetto e corsivo
|
||||
|
||||
```
|
||||
**testo in grassetto**
|
||||
_testo in corsivo_
|
||||
```
|
||||
|
||||
## Liste
|
||||
|
||||
```
|
||||
- Primo elemento
|
||||
- Secondo elemento
|
||||
- Terzo elemento
|
||||
```
|
||||
|
||||
Lista numerata:
|
||||
|
||||
```
|
||||
1. Prima cosa
|
||||
2. Seconda cosa
|
||||
3. Terza cosa
|
||||
```
|
||||
|
||||
## Link
|
||||
|
||||
```
|
||||
[testo del link](https://esempio.com)
|
||||
```
|
||||
|
||||
## Immagine
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
Le immagini si caricano dall'editor con il pulsante **+ Immagine** in fondo alla schermata di modifica.
|
||||
|
||||
## Wikilink
|
||||
|
||||
```
|
||||
[[nome-della-pagina]]
|
||||
```
|
||||
|
||||
Vedi [[wikirefs]] per tutti i dettagli.
|
||||
|
||||
## Citazione
|
||||
|
||||
```
|
||||
> Testo citato
|
||||
```
|
||||
|
||||
## Codice inline
|
||||
|
||||
```
|
||||
`codice`
|
||||
```
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
title: Remark-WikiRefs
|
||||
---
|
||||
|
||||
Il pacchetto `remark-wikirefs` è responsabile della gestione della sintassi markdown dei [[wikirefs]]. È disponibile su [GitHub](https://github.com/wikibonsai/remark-wikirefs).
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
title: Albero Semantico
|
||||
---
|
||||
|
||||
:plugin::[[semtree]]
|
||||
|
||||
L'albero semantico è costruito con il plugin [[semtree]] (vedi la documentazione per i dettagli). È definito dai documenti [[index-type]] in formato markdown. Forma una gerarchia concettuale con lo scopo di orientare il lettore all'interno dei concetti del sito.
|
||||
|
||||
Vale la pena ripeterlo:
|
||||
|
||||
> "È importante considerare la conoscenza come una sorta di albero semantico. Assicurati di comprendere i principi fondamentali — ovvero il tronco e i rami principali — prima di addentrarsi nelle foglie e nei dettagli, altrimenti non avranno nulla a cui aggrapparsi."
|
||||
>
|
||||
> ~ [Elon Musk](https://www.reddit.com/r/IAmA/comments/2rgsan/comment/cnfre0a/?utm_source=share&utm_medium=web2x&context=3)
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
title: SemTree
|
||||
---
|
||||
|
||||
Il pacchetto `semtree` è responsabile della costruzione dell'[[semantic-tree]]. È disponibile su [GitHub](https://github.com/wikibonsai/semtree).
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
title: Test Render
|
||||
date: '2023-10-05'
|
||||
---
|
||||
|
||||
Questo file serve specificamente a testare il rendering dei [[wikirefs]] come wikiembed.
|
||||
@@ -1,244 +0,0 @@
|
||||
---
|
||||
title: Test
|
||||
date: '2021-08-04'
|
||||
---
|
||||
|
||||
Questa pagina serve a testare e mostrare gli stili markdown disponibili in questo template.
|
||||
|
||||
## Markdown
|
||||
|
||||
(alcuni caratteri di escape `\` sono aggiunti per mostrare il testo grezzo)
|
||||
|
||||
### WikiRefs
|
||||
|
||||
#### WikiAttr con prefisso (vedi attrbox per l'output)
|
||||
|
||||
```markdown
|
||||
:prefixed-wikiattr::[[wikirefs]]
|
||||
```
|
||||
|
||||
:prefixed-wikiattr::[[wikirefs]]
|
||||
|
||||
#### Lista WikiAttr con prefisso (vedi attrbox per l'output)
|
||||
|
||||
```markdown
|
||||
: prefixed-wikiattr-list ::
|
||||
- [[wikirefs]]
|
||||
- [[feedback]]
|
||||
```
|
||||
|
||||
: prefixed-wikiattr-list ::
|
||||
- [[wikirefs]]
|
||||
- [[feedback]]
|
||||
|
||||
#### WikiAttr senza prefisso (vedi attrbox per il rendering)
|
||||
|
||||
```markdown
|
||||
unprefixed-wikiattr::[[wikirefs]]
|
||||
```
|
||||
|
||||
unprefixed-wikiattr::[[wikirefs]]
|
||||
|
||||
#### Lista WikiAttr senza prefisso (vedi attrbox per il rendering)
|
||||
|
||||
```markdown
|
||||
unprefixed-wikiattr-list ::
|
||||
- [[wikirefs]]
|
||||
- [[feedback]]
|
||||
```
|
||||
|
||||
unprefixed-wikiattr-list ::
|
||||
- [[wikirefs]]
|
||||
- [[feedback]]
|
||||
|
||||
#### Un WikiLink
|
||||
|
||||
```markdown
|
||||
[[digital-garden]]
|
||||
```
|
||||
|
||||
[[digital-garden]]
|
||||
|
||||
#### Un WikiLink tipizzato (controlla l'HTML per la classe CSS linktype)
|
||||
|
||||
```markdown
|
||||
:typed-wikilink::[[digital-garden]].
|
||||
```
|
||||
|
||||
:typed-wikilink::[[digital-garden]].
|
||||
|
||||
#### Un WikiEmbed (Markdown)
|
||||
|
||||
```markdown
|
||||
![[test-render]]
|
||||
```
|
||||
|
||||
![[test-render]]
|
||||
|
||||
#### Un WikiEmbed (Immagine)
|
||||
|
||||
```markdown
|
||||
![[wikibonsai-way.png]]
|
||||
```
|
||||
|
||||
![[wikibonsai-way.png]]
|
||||
|
||||
#### Zombie (link a pagine inesistenti)
|
||||
|
||||
#### WikiAttr con prefisso zombie (vedi attrbox per il rendering)
|
||||
|
||||
```markdown
|
||||
:zombie-wikiattr::[[zombie]]
|
||||
```
|
||||
|
||||
:zombie-wikiattr::[[zombie]]
|
||||
|
||||
#### Lista WikiAttr con prefisso zombie (vedi attrbox per il rendering)
|
||||
|
||||
```markdown
|
||||
: zombie-wikiattr-list ::
|
||||
- [[zombie-1]]
|
||||
- [[zombie-2]]
|
||||
```
|
||||
|
||||
: zombie-wikiattr-list ::
|
||||
- [[zombie-1]]
|
||||
- [[zombie-2]]
|
||||
|
||||
#### WikiAttr senza prefisso zombie (vedi attrbox per il rendering)
|
||||
|
||||
```markdown
|
||||
zombie-wikiattr::[[zombie]]
|
||||
```
|
||||
|
||||
zombie-wikiattr::[[zombie]]
|
||||
|
||||
#### Lista WikiAttr senza prefisso zombie (vedi attrbox per il rendering)
|
||||
|
||||
```markdown
|
||||
zombie-wikiattr-list ::
|
||||
- [[zombie-1]]
|
||||
- [[zombie-2]]
|
||||
```
|
||||
|
||||
zombie-wikiattr-list ::
|
||||
- [[zombie-1]]
|
||||
- [[zombie-2]]
|
||||
|
||||
#### WikiLink zombie
|
||||
|
||||
```markdown
|
||||
[[zombie]]
|
||||
```
|
||||
|
||||
[[zombie]]
|
||||
|
||||
#### WikiLink tipizzato zombie
|
||||
|
||||
```markdown
|
||||
:zombie-typed-wikilink::[[zombie]].
|
||||
```
|
||||
|
||||
:zombie-typed-wikilink::[[zombie]].
|
||||
|
||||
#### WikiEmbed zombie
|
||||
|
||||
```markdown
|
||||
![[zombie]]
|
||||
```
|
||||
|
||||
![[zombie]]
|
||||
|
||||
#### Intestazioni
|
||||
|
||||
```markdown
|
||||
# Intestazione 1
|
||||
## Intestazione 2
|
||||
### Intestazione 3
|
||||
#### Intestazione 4
|
||||
##### Intestazione 5
|
||||
###### Intestazione 6
|
||||
```
|
||||
|
||||
# Intestazione 1
|
||||
## Intestazione 2
|
||||
### Intestazione 3
|
||||
#### Intestazione 4
|
||||
##### Intestazione 5
|
||||
###### Intestazione 6
|
||||
|
||||
#### Liste
|
||||
|
||||
```markdown
|
||||
- Uno
|
||||
- Due
|
||||
- Tre
|
||||
```
|
||||
|
||||
- Uno
|
||||
- Due
|
||||
- Tre
|
||||
|
||||
#### Citazione
|
||||
|
||||
```markdown
|
||||
> Citazione.
|
||||
```
|
||||
|
||||
> Citazione.
|
||||
|
||||
#### Link web
|
||||
|
||||
```markdown
|
||||
[Link web](https://astro-bloomz.netlify.app)
|
||||
```
|
||||
|
||||
[Link web](https://astro-bloomz.netlify.app)
|
||||
|
||||
#### Blocco di codice
|
||||
|
||||
```javascript
|
||||
// javascript
|
||||
for (var i=1; i < 101; i++){
|
||||
if (i % 15 == 0) console.log("FizzBuzz");
|
||||
else if (i % 3 == 0) console.log("Fizz");
|
||||
else if (i % 5 == 0) console.log("Buzz");
|
||||
else console.log(i);
|
||||
}
|
||||
```
|
||||
|
||||
```ruby
|
||||
# ruby
|
||||
1.upto 100 do |i|
|
||||
string = ""
|
||||
string += "Fizz" if i % 3 == 0
|
||||
string += "Buzz" if i % 5 == 0
|
||||
puts "#{i} = #{string}"
|
||||
end
|
||||
```
|
||||
|
||||
#### Codice inline
|
||||
|
||||
```markdown
|
||||
Va bene, `va bene`, va bene.
|
||||
```
|
||||
|
||||
Va bene, `va bene`, va bene.
|
||||
|
||||
#### Tabelle
|
||||
|
||||
```markdown
|
||||
| Conigli | Volpi | Ricci |
|
||||
|:------- |:-----:| -----:|
|
||||
| 25 | 3 | 12 |
|
||||
| 100 | 10 | 20 |
|
||||
```
|
||||
|
||||
| Conigli | Volpi | Ricci |
|
||||
|:------- |:-----:| -----:|
|
||||
| 25 | 3 | 12 |
|
||||
| 100 | 10 | 20 |
|
||||
|
||||
#### Testo lungo
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla imperdiet, eros in aliquet eleifend, felis tellus laoreet velit, a feugiat purus mi at arcu. Sed tempor congue gravida. Suspendisse sodales ultricies lacus, nec consequat mauris dictum in. Aliquam at lacus sodales, porta velit in, consequat mauris. Maecenas consequat fermentum tortor, vitae tincidunt sem porta vel. Sed elementum dui libero, vitae bibendum est imperdiet non. Curabitur sit amet libero quis nulla faucibus euismod. Cras condimentum ante tortor, a sollicitudin elit accumsan eget.
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
title: WikiBonsai
|
||||
---
|
||||
|
||||
![[wikibonsai-way.png]][^twt]
|
||||
|
||||
Astro-Bloomz è un progetto [WikiBonsai](https://github.com/wikibonsai/wikibonsai).
|
||||
|
||||
![[astro-bloomz]]
|
||||
|
||||
|
||||
[^twt]: [spiegazione](https://twitter.com/wibomd/status/1703930973371412699)
|
||||
+26
-8
@@ -1,19 +1,37 @@
|
||||
---
|
||||
title: WikiRefs
|
||||
title: Come usare i wikilink
|
||||
---
|
||||
|
||||
plugin::[[remark-wikirefs]]
|
||||
Un wikilink collega una pagina a un'altra. Si scrive così:
|
||||
|
||||
```
|
||||
[[nome-della-pagina]]
|
||||
```
|
||||
|
||||
I `[[WikiRefs]]`[^nomi] sono una parte fondamentale del mondo del [[digital-garden|digital gardening]]. Sono il mattone di base dell'interconnessione realizzata in molti giardini digitali, incluso questo. Vengono renderizzati con il plugin [[remark-wikirefs]], appaiono in un colore diverso rispetto ai link web esterni, e puoi consultare quella documentazione per ulteriori dettagli.
|
||||
## Come funziona
|
||||
|
||||
In breve, questo particolare tipo di `[[wikirefs]]` comprende tre costrutti wiki: wikiattr, wikilink e wikimbed.
|
||||
Scrivi il nome della pagina tra doppie parentesi quadre. Il sistema crea il link automaticamente. Nella pagina collegata comparirà in fondo la lista delle pagine che la citano.
|
||||
|
||||
I _WikiAttr_ sono attributi formalizzati di un file. Includono un tipo di attributo descrittivo e un wikilink a un altro file. Si scrivono `:così::[[wikilink]]` (con un'a capo dopo) e vengono renderizzati nell'attributebox (attrbox).
|
||||
## Esempio
|
||||
|
||||
I _WikiLink_ sono i tradizionali link bidirezionali con la sintassi a parentesi quadre e possono comparire ovunque in un file. Esistono `:tipizzati::[[wikilink]]` e normali `[[wikilink]]` non tipizzati. Sono evidenziati in un colore diverso rispetto ai link web esterni.
|
||||
Stai scrivendo un racconto di un tour e vuoi rimandare alla pagina sull'equipaggiamento:
|
||||
|
||||
I _WikiEmbed_ incorporano il contenuto del file collegato direttamente nella pagina corrente. È possibile incorporare file markdown, immagini, audio o video. I WikiEmbed si scrivono `![[così]]`.
|
||||
```
|
||||
Per i dettagli su cosa portare, vedi [[zaino-da-bikepacking]].
|
||||
```
|
||||
|
||||
## Collegare una categoria
|
||||
|
||||
[^nomi]: "wikiref" porta in realtà molti nomi: "[wikilink](https://en.wikipedia.org/wiki/Help:Link)", "[link bidirezionale](https://maggieappleton.com/bidirectionals)", "[wikitext linking](https://tiddlywiki.com/#Linking%20in%20WikiText)", "backlink", "[link interno](https://help.obsidian.md/How+to/Internal+link)", per citarne solo alcuni...
|
||||
Per posizionare una pagina sotto una categoria, aggiungi il wikilink della categoria da qualche parte nel testo:
|
||||
|
||||
```
|
||||
Questo fa parte di [[BincioTour]].
|
||||
```
|
||||
|
||||
Le categorie disponibili sono: [[BincioTech]], [[BincioOfficina]], [[BincioTour]], [[BincioCorsa]], [[BincioAbbigliamento]].
|
||||
|
||||
Nell'editor, il wikilink della categoria viene inserito automaticamente quando scegli la sezione dal menu.
|
||||
|
||||
## Il nome nel link
|
||||
|
||||
Il nome nel link deve corrispondere esattamente al nome file della pagina (senza `.md`). Se la pagina si chiama `garmin-edge-540.md`, il link sarà `[[garmin-edge-540]]`.
|
||||
|
||||
@@ -1,118 +1,59 @@
|
||||
---
|
||||
title: 'Come funziona questo giardino digitale (e perché esiste)'
|
||||
title: Come funziona questo wiki
|
||||
pubDate: '2026-05-02'
|
||||
description: 'Una guida semplice per capire la struttura e come contribuire'
|
||||
---
|
||||
|
||||
## Cos'è un giardino digitale?
|
||||
## Cos'è
|
||||
|
||||
Un giardino digitale è diverso da un blog. Un blog ha pagine ordinate per data — la più recente è in primo piano. Un giardino digitale è come un orto vero: crescono insieme tante cose diverse, ognuna con i propri tempi, e tutto è collegato.
|
||||
Un posto dove raccogliamo quello che vogliamo non dimenticare: gite, riparazioni, gear, allenamenti. Non è un blog con post ordinati per data — è più come un archivio vivo, dove le pagine si collegano tra loro e si aggiornano nel tempo.
|
||||
|
||||
Qui raccogliamo:
|
||||
- Ricordi di cose che abbiamo fatto insieme
|
||||
- Idee e spunti che tornano utili
|
||||
- Documentazione tecnica quando serve
|
||||
- Semplicemente: le cose che vogliamo non dimenticare
|
||||
## Due sezioni
|
||||
|
||||
## La struttura
|
||||
**Blog** — Storie e ricordi. Cose che abbiamo fatto: "Bike trip in Marocco", "Quella volta che ci ha piovuto addosso a 2000m".
|
||||
|
||||
### Due sezioni
|
||||
**Pagine** — Guide e riferimenti. Cose che tornano utili: "Come riparare la catena", "Quale lubrificante per la pioggia".
|
||||
|
||||
**📝 Blog** — Storie, ricordi, avventure in bicicletta. Esempi: "Bike trip to Morocco", "Barcelona—Valencia non-stop", "Quella volta che ci è piovuto addosso a 2000m".
|
||||
Se non sai dove mettere qualcosa, scegli Pagine. Si può spostare.
|
||||
|
||||
**📚 Pages** — Guide, spiegazioni, riferimenti. Esempi: "Come riparare la catena", "Quali sono le categorie", "Come usare i wikilink".
|
||||
## Categorie
|
||||
|
||||
### Wikilink — i fili che tengono insieme tutto
|
||||
Le pagine sono organizzate in cinque categorie. Vedi [[come-usare-le-categorie]] per scegliere quella giusta.
|
||||
|
||||
Quando scrivi su questo giardino, puoi collegare le cose con una sintassi speciale: `[[nome-della-pagina]]`.
|
||||
Quando crei una pagina dall'editor, scegli la categoria dal menu — il sistema la posiziona nel posto giusto automaticamente.
|
||||
|
||||
Esempio:
|
||||
- Scrivi un racconto su una escursione: "[[Escursione alle Tre Cime]]"
|
||||
- In fondo al racconto, aggiungi: "Leggi anche [[Escursione al Monte Baldo]]"
|
||||
- Nel sito vedi automaticamente il collegamento, e il lettore può saltare da una storia all'altra
|
||||
## Wikilink
|
||||
|
||||
Non serve elencare tutti i link a mano — il sistema li scopre da solo e li mostra alla fine di ogni pagina.
|
||||
|
||||
### L'albero — bonsai
|
||||
|
||||
Tutte le pagine sono organizzate in un albero gerarchico. Operativamente, funziona così:
|
||||
|
||||
**La pagina "BincioTech"** esiste come pagina vera e propria. Altre pagine la referenziano con un wikilink — ad esempio una pagina su "Review del Garmin" dirà: "Vedi anche [[BincioTech]]".
|
||||
|
||||
Quando il sito vede questi collegamenti, costruisce automaticamente l'albero. Quindi:
|
||||
Puoi collegare una pagina a un'altra scrivendo il nome tra doppie parentesi quadre:
|
||||
|
||||
```
|
||||
BincioTech
|
||||
├─ Review del Garmin
|
||||
├─ Come sincronizzare il power meter
|
||||
└─ Lights comparision
|
||||
|
||||
BincioOfficina
|
||||
├─ Come pulire la catena
|
||||
├─ Riparazione del cambio
|
||||
└─ Cuscinetti rotti?
|
||||
[[nome-della-pagina]]
|
||||
```
|
||||
|
||||
**Quindi, operativamente:**
|
||||
Esempio: stai scrivendo di un bike packing e vuoi rimandare a una pagina sull'equipaggiamento:
|
||||
|
||||
1. Crei una pagina normale: `review-del-garmin.md`
|
||||
2. Dentro scrivi: "Questo è un componente di [[BincioTech]]"
|
||||
3. Il sito vede il wikilink e posiziona la pagina sotto BincioTech nell'albero
|
||||
4. Quando leggi "Review del Garmin", vedi il percorso: `BincioTech > Review del Garmin`
|
||||
|
||||
Non serve fare nulla di complicato — basta usare il wikilink giusto nella pagina e il resto succede da solo.
|
||||
|
||||
## Come contribuire
|
||||
|
||||
### Creare una pagina
|
||||
|
||||
1. Una pagina è un semplice file di testo (Markdown)
|
||||
2. Ha un titolo e una data
|
||||
3. Dentro scrivi con il linguaggio che usi per gli SMS e le email — niente complicazioni
|
||||
4. Aggiungi i wikilink dove ha senso: `[[Pagina Collegata]]`
|
||||
|
||||
Esempio di pagina:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Quel sabato che eravamo ubriachi al bar"
|
||||
date: '2025-05-01'
|
||||
---
|
||||
|
||||
Ricordo ancora il primo drink che ci ha ordinato Giancarlo...
|
||||
|
||||
Successivamente siamo andati a [[La pizzeria dove sempre andiamo]].
|
||||
```
|
||||
Per i dettagli su cosa portare, vedi [[zaino-da-bikepacking]].
|
||||
```
|
||||
|
||||
### Nome della pagina
|
||||
Il collegamento appare nel testo, e nella pagina collegata comparirà automaticamente "citata da questa pagina" in fondo. Non devi fare altro.
|
||||
|
||||
Il nome è importante per i wikilink. Usa:
|
||||
- Parole normali, non gergo
|
||||
- Maiuscola all'inizio: `Escursione alle Tre Cime`, non `escursione alle tre cime`
|
||||
- Trattini al posto degli spazi: `Escursione-alle-Tre-Cime`
|
||||
- Descrittivo: `Racconto di Marco`, non `cosa`
|
||||
Per collegare una pagina alla sua categoria, aggiungi il wikilink della categoria nel testo:
|
||||
|
||||
### Dove mettere la pagina?
|
||||
```
|
||||
Questo fa parte di [[BincioTour]].
|
||||
```
|
||||
|
||||
Se è un **ricordo o una storia**: va nella sezione pagine "blog"
|
||||
Se è una **guida o documentazione**: va nella sezione "pages"
|
||||
## Come creare una pagina
|
||||
|
||||
Chi lo decide? Dipende dal contenuto. Se non sei sicuro, inizia con le pagine recenti — puoi sempre spostarlo.
|
||||
1. Clicca il pulsante di modifica nel sito
|
||||
2. Scegli la sezione e la sottosezione dal menu
|
||||
3. Scrivi un nome breve per la pagina (es. `garmin-edge-540-review`)
|
||||
4. Scrivi il contenuto in markdown — vedi [[markdown]] per la sintassi
|
||||
5. Salva
|
||||
|
||||
## L'ordine delle cose — tema e gerarchia
|
||||
## Consigli pratici
|
||||
|
||||
Prima che tutti iniziate a scrivere, vogliamo stabilire un sistema di temi. Immagina di dire:
|
||||
|
||||
> "Tutte le storie di gite sono sotto Ricordi → Escursioni"
|
||||
> "Tutte le ricette sono sotto Tecniche → Cucina"
|
||||
|
||||
Così quando leggi una pagina, vedi il percorso che l'ha raggiunta. Non è un'imposizione rigida — è più un'organizzazione che rende facile muoversi.
|
||||
|
||||
## Riassumendo
|
||||
|
||||
- **Scrivi in italiano, in modo naturale** — come se stessi scrivendo a un amico
|
||||
- **Collega le pagine con wikilink** — `[[Così]]` — e tutto il resto succede da solo
|
||||
- **Non preoccuparti della perfezione** — un giardino si evolve nel tempo
|
||||
- **Scegli un nome chiaro** per la pagina, così gli altri sanno di cosa parla
|
||||
|
||||
Pronto? Allora, piantare il primo seme. 🌱
|
||||
- **Scrivi in italiano, come se scrivessi a un amico** — niente gergo, niente formalismi
|
||||
- **Usa un nome descrittivo** per la pagina: `riparazione-raggi-ruota-posteriore` è meglio di `riparazione`
|
||||
- **Aggiungi wikilink** dove ha senso — collegare le pagine le rende più utili nel tempo
|
||||
- **Non serve che sia perfetto** — si può sempre modificare
|
||||
|
||||
@@ -1,117 +1,80 @@
|
||||
---
|
||||
title: 'Come usare le categorie Bincio'
|
||||
date: '2026-05-02'
|
||||
title: Come scegliere la categoria
|
||||
pubDate: '2026-05-02'
|
||||
---
|
||||
|
||||
Abbiamo organizzato il giardino in 5 categorie principali. Ognuna ha uno scopo preciso.
|
||||
Le pagine sono organizzate in cinque categorie. Scegli quella che descrive meglio l'argomento principale.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 BincioTech
|
||||
|
||||
Tutto quello che riguarda **tecnologia, gadget e gear** della bicicletta.
|
||||
Tecnologia, gadget e componenti della bici.
|
||||
|
||||
**Esempi di contenuti:**
|
||||
- "Ho comprato questo ciclocomputer e fa così"
|
||||
- "Confronto tra trasmettitori di potenza: quale scegliere?"
|
||||
- "Ho comprato questo ciclocomputer, ecco cosa fa"
|
||||
- "Confronto tra power meter: quale scegliere?"
|
||||
- "Come sincronizzare il Garmin con il telefono"
|
||||
- "Review della nuova cassa Bluetooth impermeabile"
|
||||
- "Sensori di cadenza: quali funzionano davvero"
|
||||
|
||||
**Sottocategorie:**
|
||||
- Gear e accessori (Garmin, contachilometri, luci, power meter...)
|
||||
- Componenti e upgrade (gruppi, freni, ruote...)
|
||||
- Tecnologia e elettronica (software, app, sincronizzazioni...)
|
||||
**Sottocategorie:** Gear e accessori · Componenti e upgrade · Tecnologia e elettronica
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ BincioOfficina
|
||||
|
||||
**Manutenzione, riparazioni e lavori fai-da-te**.
|
||||
Manutenzione, riparazioni e lavori fai-da-te.
|
||||
|
||||
**Esempi di contenuti:**
|
||||
- "Come pulire la catena correttamente (senza fare danni)"
|
||||
- "Mi si è rotto lo spallamento, ecco come l'ho riparato"
|
||||
- "Guida al cambio dei cuscinetti"
|
||||
- "Ho tolto la ruggine dal telaio, metodo infallibile"
|
||||
- "Come pulire la catena senza fare danni"
|
||||
- "Mi si è rotto il deragliatore, ecco come l'ho riparato"
|
||||
- "Lubrificanti consigliati per la pioggia"
|
||||
|
||||
**Sottocategorie:**
|
||||
- Manutenzione (pulizia, lubrificazione, controlli periodici...)
|
||||
- Riparazioni (catena spezzata, freni che non frenano...)
|
||||
- Fai da te (tool DIY, upgrade casalinghi, creatività...)
|
||||
**Sottocategorie:** Manutenzione · Riparazioni · Fai da te
|
||||
|
||||
---
|
||||
|
||||
## 🗺️ BincioTour
|
||||
|
||||
**Tour report, bike packing, rotte e logistica**.
|
||||
Tour, bike packing, rotte e logistica.
|
||||
|
||||
**Esempi di contenuti:**
|
||||
- "Abbiamo fatto 120 km in un giorno, ecco la rotta"
|
||||
- "Primo bike packing, cosa ho imparato"
|
||||
- "Primo bike packing: cosa ho imparato"
|
||||
- "La strada verso le Tre Cime: mappa e consigli"
|
||||
- "Come organizzare un'escursione a bicicletta"
|
||||
- "Ho pernottato all'aperto, ecco cosa serviva"
|
||||
|
||||
**Sottocategorie:**
|
||||
- Tour report (quello che abbiamo fatto, come è andata, foto...)
|
||||
- Bike packing (zaini, borse, come caricare il peso...)
|
||||
- Rotte e itinerari (mappe, difficoltà, panorami...)
|
||||
- Logistica (dove dormire, dove mangiare, servizi...)
|
||||
**Sottocategorie:** Tour report · Bike packing · Rotte e itinerari · Logistica
|
||||
|
||||
---
|
||||
|
||||
## 🏁 BincioCorsa
|
||||
|
||||
**Allenamento, gare e performance**.
|
||||
Allenamento, gare e performance.
|
||||
|
||||
**Esempi di contenuti:**
|
||||
- "Quest'anno mi alleno con questo metodo"
|
||||
- "Report dalla gara: mi sono rotto il record personale"
|
||||
- "Analisi dei dati di allenamento: cosa ho imparato"
|
||||
- "I miei 100 km più difficili: ecco i dati"
|
||||
- "Preparazione mentale prima della competizione"
|
||||
- "Report dalla gara: nuovo record personale"
|
||||
- "Analisi dei dati di allenamento"
|
||||
|
||||
**Sottocategorie:**
|
||||
- Allenamento (programmi, metodi, tracce...)
|
||||
- Gare e competizioni (risultati, strategie, sfide...)
|
||||
- Performance (dati, analisi, progressi...)
|
||||
**Sottocategorie:** Allenamento · Gare e competizioni · Performance
|
||||
|
||||
---
|
||||
|
||||
## 👕 BincioAbbigliamento
|
||||
|
||||
**Abbigliamento tecnico, comfort e protezione**.
|
||||
Abbigliamento tecnico, comfort e protezione.
|
||||
|
||||
**Esempi di contenuti:**
|
||||
- "Ho provato questa giacca da ciclocross, è impermeabile davvero?"
|
||||
- "Quale sottopiede per l'inverno?"
|
||||
- "Salopette da donna: quale funziona meglio"
|
||||
- "Protezioni per il sole: creme e abbigliamento"
|
||||
- "Questo giubbotto è comodo anche se strappato"
|
||||
- "Ho provato questa giacca: è davvero impermeabile?"
|
||||
- "Quale salopette per l'inverno?"
|
||||
- "Guanti per il freddo: confronto"
|
||||
|
||||
**Sottocategorie:**
|
||||
- Abbigliamento tecnico (maglie, giacche, pantaloncini...)
|
||||
- Comfort e protezione (guanti, scarpette, casco...)
|
||||
- Stagionalità (estate, inverno, pioggia, caldo...)
|
||||
**Sottocategorie:** Abbigliamento tecnico · Comfort e protezione · Stagionalità
|
||||
|
||||
---
|
||||
|
||||
## 📝 Come scegliere la categoria giusta?
|
||||
## Come scegliere
|
||||
|
||||
Semplice: **qual è il motivo principale per cui stai scrivendo?**
|
||||
Chiediti: **qual è il motivo principale per cui stai scrivendo?**
|
||||
|
||||
- **È una storia di una gita?** → [[BincioTour]]
|
||||
- **Stai raccontando di una riparazione o di manutenzione?** → [[BincioOfficina]]
|
||||
- **Parli di un gadget, un sensore, o una app?** → [[BincioTech]]
|
||||
- **È un risultato di una gara o allenamento?** → [[BincioCorsa]]
|
||||
- **È su cosa indossare?** → [[BincioAbbigliamento]]
|
||||
- Racconto di una gita → [[BincioTour]]
|
||||
- Riparazione o manutenzione → [[BincioOfficina]]
|
||||
- Gadget, sensore o app → [[BincioTech]]
|
||||
- Gara o allenamento → [[BincioCorsa]]
|
||||
- Cosa indossare → [[BincioAbbigliamento]]
|
||||
|
||||
Se ancora non sei sicuro, non preoccuparti: scegline una e chi gestisce il sito può spostarlo se serve.
|
||||
|
||||
---
|
||||
|
||||
## Il punto cruciale
|
||||
|
||||
Non è un'imposizione. È una mappa che aiuta gli altri a navigare. Quando leggi una pagina, vedi dove si trova nell'albero, e da lì puoi saltare ad altri contenuti correlati.
|
||||
|
||||
Scrivi naturalmente, collega le pagine con `[[così]]`, e il resto succede da solo.
|
||||
Se non sei sicuro, scegli la più vicina. Chi gestisce il sito può spostare la pagina se serve.
|
||||
|
||||
@@ -7,6 +7,7 @@ dependencies = [
|
||||
"uvicorn[standard]>=0.30.0",
|
||||
"pydantic>=2.0.0",
|
||||
"bcrypt>=4.0.0",
|
||||
"python-multipart>=0.0.27",
|
||||
]
|
||||
|
||||
[tool.uv]
|
||||
|
||||
+1
-1
Submodule site updated: 3e82221af5...7101956a2e
@@ -111,6 +111,7 @@ dependencies = [
|
||||
{ name = "bcrypt" },
|
||||
{ name = "fastapi" },
|
||||
{ name = "pydantic" },
|
||||
{ name = "python-multipart" },
|
||||
{ name = "uvicorn", extra = ["standard"] },
|
||||
]
|
||||
|
||||
@@ -119,6 +120,7 @@ requires-dist = [
|
||||
{ name = "bcrypt", specifier = ">=4.0.0" },
|
||||
{ name = "fastapi", specifier = ">=0.115.0" },
|
||||
{ name = "pydantic", specifier = ">=2.0.0" },
|
||||
{ name = "python-multipart", specifier = ">=0.0.27" },
|
||||
{ name = "uvicorn", extras = ["standard"], specifier = ">=0.30.0" },
|
||||
]
|
||||
|
||||
@@ -339,6 +341,15 @@ wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "python-multipart"
|
||||
version = "0.0.27"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/69/9b/f23807317a113dc36e74e75eb265a02dd1a4d9082abc3c1064acd22997c4/python_multipart-0.0.27.tar.gz", hash = "sha256:9870a6a8c5a20a5bf4f07c017bd1489006ff8836cff097b6933355ee2b49b602", size = 44043, upload-time = "2026-04-27T10:51:26.649Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/99/78/4126abcbdbd3c559d43e0db7f7b9173fc6befe45d39a2856cc0b8ec2a5a6/python_multipart-0.0.27-py3-none-any.whl", hash = "sha256:6fccfad17a27334bd0193681b369f476eda3409f17381a2d65aa7df3f7275645", size = 29254, upload-time = "2026-04-27T10:51:24.997Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pyyaml"
|
||||
version = "6.0.3"
|
||||
|
||||
Reference in New Issue
Block a user