Εμφάνιση πολύχρωμων τετραγώνων στο AsciiDoc: Πρακτικός οδηγός
Δημοσιεύτηκε 01 November 2025
Εισαγωγή
Κατά τη σύνταξη τεχνικής τεκμηρίωσης, ειδικά για οδηγούς στυλ ή προδιαγραφές διεπαφής χρήστη, είναι συχνή η ανάγκη να εμφανίζονται παλέτες χρωμάτων. Το AsciiDoc, αν και πολύ ισχυρό για τεκμηρίωση, δεν προσφέρει ενδογενή σύνταξη για την εμφάνιση δείγμάτων χρωμάτων. Αυτό το άρθρο εξετάζει το πρόβλημα και προτείνει μια ελεγκτική λύση βασισμένη στην εγχέριση HTML.
Το ζήτημα
Περιβάλλον χρήσης
Φανταστείτε ότι τεκμηριώνετε τις μεταβλητές CSS ενός θέματος εφαρμογής ιστού. Χρειάζεστε:
-
Λίστα τα δεκαεξαδικά κώδικα χρώματος
-
Εμφάνιση οπτικής προespισκόπησης каждый χρώματος
-
διατήρηση της αναγνωσιμότητας του εγγράφου προέλευσης
-
Εξασφαλίστε τη συμβατότητα με τους δημιουργούς στατικών ιστοτόπων όπως το JBake
@startuml
left to right direction
skinparam packageStyle rectangle
actor "Τεχνικός Συγγραφέας" as writer
actor "Αναγνώστης" as reader
rectangle "Τεκμηρίωση AsciiDoc" {
usecase "Τεκμηρίωση παλέτας χρωμάτων" as UC1
usecase "Εμφάνιση δεκαεξαδικού κώδικα" as UC2
usecase "Οπτικοποίηση χρώματος" as UC3
usecase "Δημιουργία στατικού ιστότοπου" as UC4
usecase "Διαβάζοντας την τεκμηρίωση" as UC5
}
writer --> UC1
UC1 ..> UC2 : include
UC1 ..> UC3 : include
UC1 --> UC4
UC4 --> UC5
UC5 <-- reader
@enduml
Οι δυνατές προσεγγίσεις
Υπολογίζονται διάφορες λύσεις για να εμφανιστούν χρώματα σε ένα έγγραφο AsciiDoc :
@startuml
skinparam componentStyle rectangle
package "Πιθανές λύσεις" {
component "Χαρακτήρες Unicode" as unicode
component "Εξωτερικές εικόνες" as images
component "Προσαρμοσμένοι ρόλοι CSS" as css
component "Έγχυση HTML" as html
}
package "Κριτήρια αξιολόγησης" {
component "Απλότητα" as simple
component "Μεταφοριστότητα" as portable
component "Προσαρμογή" as custom
component "Συντήρηση" as maintain
}
unicode -down-> simple : ✓
unicode -down-> portable : ✓
unicode -down-> custom : ✗
images -down-> simple : ✗
images -down-> portable : ✗
images -down-> custom : ✓
css -down-> simple : ~
css -down-> portable : ✗
css -down-> custom : ✓
html -down-> simple : ✓
html -down-> portable : ✓
html -down-> custom : ✓✓
html -down-> maintain : ✓
note right of html
Προτεινόμενη λύση
end note
@enduml
Επιλογή 1: Unicode χαρακτήρες
Η χρήση χαρακτήρων Unicode όπως`■`(■) είναι απλή αλλά περιορισμένη:
* ■ --accent-color: #7952b3 (violet Bootstrap)Limitations : Δεν υπάρχει έλεγχος του χρώματος, εξαρτάται από τη γραμματοσειρά του συστήματος.
Επιλογή 2 : Εξωτερικές εικόνες
Δημιουργήστε εικόνες PNG ή SVG για κάθε χρώμα :
* image:colors/violet.svg[width=16] --accent-color: #7952b3Limitations : Βαρέα συντήρηση, πολλαπλασιασμός των αρχείων, χωρίς αυτόματο συγχρονισμό.
Επιλογή 3 : Προσαρμοσμένοι ρόλοι CSS
Καθορίστε κλάσεις CSS και εφαρμόστε τις μέσω ρόλων AsciiDoc :
* [.color-violet]##■## --accent-color: #7952b3Περιορισμοί : Απαιτείται ένα εξωτερικό φύλλο στυλ, ο προκαhtoρισμός όλων των πιθανών χρωμάτων.
Επιλογή 4 : Ένθεση HTML (επιλεγμένη λύση)
Χρησιμοποιήστε τη μακροεντολή``για να ενετελλάτε HTML με ενσωματωμένα στυλ :
* pass:[<span style="display:inline-block;width:1em;height:1em;
background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>]
--accent-color: #7952b3 (violet Bootstrap)Η λύση : Ένθεση HTML με
αρχή λειτουργίας
Το μάκρο``Το d’AsciiDoc επιτρέπει την εισαγωγή απλής περιεχομένου που δεν θα ερμηνευθεί από τον επεξεργαστή AsciiDoc. Αυτό μας επιτρέπει να εγχωρίσουμε απευθείας HTML με ενσωματωμένα στυλ CSS.
@startuml participant "Έγγραφο\nAsciiDoc" as doc participant "Επεξεργαστής\nAsciiDoc" as processor participant "macro pass:[]" as pass participant "HTML\nτελικό" as html doc -> processor : Analyse document processor -> pass : Détecte pass:[] pass -> processor : Retourne HTML brut processor -> html : Insère sans transformation html -> html : Navigateur applique styles @enduml
Υλοποίηση
Αυτό είναι η δομή HTML που θα ενσωματωθεί :
<span style="display:inline-block;
width:1em;
height:1em;
background:#7952b3;
vertical-align:middle;
margin-right:0.5em">
</span>Επεξήγηση των ιδιοτήτων CSS
| Ιδιότητα | Λειτουργία |
|---|---|
|
Επιτρέπει τον ορισμό του width/height ενώ παραμένει στη γραμμική ροή |
|
Μέγεθος τετράγωνου σχετικό με το μέγεθος γραμματοσειράς (ανταποκρινόμενο) |
|
Το χρώμα που θα εμφανιστεί (μεταβλητό σύμφωνα με τις ανάγκες σας) |
|
Συμμετρόν το τετράγωνο με το κείμενο δίπλα |
|
διάστημα μεταξύ του τετραγώνου και του κειμένου |
Πλήρες παράδειγμα
Αυτό είναι ένα παράδειγμα που τεκμηριώνει μια χρωματική παλέτα θέματος :
== Thème Clair
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span>] --accent-hover: `#61428f` (violet plus foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --card-bg: `#ffffff` (blanc)Ποιος παράγει το επόμενο αποτέλεσμα :
Φεγγαρό Θέμα
-
--bg-primary:`#f8f9fa`(λευκόπρινο)
-
--text-primary:`#212529`(πολύ σκούρο μαύρο)
-
--accent-color:`#7952b3`(βιολέτι Bootstrap)
-
--accent-hover:`#61428f`(πιο σκούρο βιολέ)
-
--card-bg:`#ffffff`(λευκό)
Βελτιστοποιήσεις και καλές πρακτικές
Διαχείριση των φωτεινών χρωμάτων
Για πολύ ανοιχτές χρωματικές τόνες (λευκό, πολύ ανοιχτό γκρι), προσθέστε ένα περίγραμμα για να γίνουν ορατά σε λευκό φόντο :
<span style="display:inline-block;width:1em;height:1em;
background:#ffffff;border:1px solid #ccc;
vertical-align:middle;margin-right:0.5em"></span>Η γκρίζη περίγραμμα`border:1px solid #ccc`) επιτρέπει να οριοθετήσει το λευκό τετράγωνο σε ένα λευκό φόντο.
Προσαρμόστε το μέγεθος των τετραγώνων
Μπορείτε να προσαρμόσετε το μέγεθος των τετραγώνων ανάλογα με τις ανάγκες σας :
* pass:[<span style="display:inline-block;width:1.5em;height:1.5em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Grand carré
* pass:[<span style="display:inline-block;width:0.8em;height:0.8em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Petit carréΗ χρήση της μονάδας`em`Εγγυάται ότι τα τετράγωνα προσαρμόζονται στο μέγεθος της γραμματοσειράς.
Δημιουργήστε παραλλαγές
Για συγκεκριμένες ανάγκες, μπορείτε να δημιουργήσετε διάφορες μορφές:
χρωστός κύκλος
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violetΤετράγωνο με χρωματικό περίθωριο
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:3px solid #7952b3;vertical-align:middle;margin-right:0.5em"></span>] Bordure violetteΑρχιτεκτονική της λύσης
@startuml
package "Ροή εργασίας τεκμηρίωσης" {
[Document AsciiDoc\navec pass macro] as asciidoc
[Processeur JBake] as jbake
[Site HTML statique] as html
[Navigateur Web] as browser
}
asciidoc --> jbake : 1. Compilation
jbake --> html : 2. Génération
html --> browser : 3. Affichage
browser --> browser : 4. Rendu CSS
note right of asciidoc
Περιέχει τις ετικέτες
`pass:[]` με inline HTML
end note
note right of jbake
Διατήρησε το HTML
στο pass:[]
end note
note right of browser
Εφαρμόστε τα στυλ
inline CSS
end note
@enduml
Πλεονεκτήματα και περιορισμοί
Πλεονεκτήματα
-
✓ Autonomie : Καμία εξάρτηση από εξωτερικά αρχεία
-
�✓ Προσαρμοστικότητα : Λειτουργεί με όλους τους επεξεργαστές AsciiDoc
-
✓ Synchronisation : Ο κωδικός χρώματος είναι απευθείας στο HTML
-
✓ Flexibilité : Πλήρης προσαρμογή του στυλ
-
✓ Maintenance : Απλὴ τροποποίηση του δεκαεξαδικού κώδικα
-
�✓ Συμβατότητα JBake : Λειτουργεί τέλεια με τις γεννητέρες στατικών ιστοτόπων
Περιορισμοί
-
�✗ λογοριθμία : Κώδικας HTML επαναλαμβανόμενος στην πηγή AsciiDoc
-
Αναγνωσιμότητα πηγής : Το έγγραφο πηγής είναι λιγότερο καθαρό
-
Accessibilité : Δεν υπάρχει εγγενές εναλλακτικό κείμενο (να προστεθεί χειροκίνητα)
Βελτίωση της προσβασιμότητας
Για να κάνετε τα τετράγωνα προσβάσιμα στους αναγνώστες οθόνης:
* pass:[<span role="img" aria-label="Couleur violet Bootstrap"
style="display:inline-block;width:1em;height:1em;background:#7952b3;
vertical-align:middle;margin-right:0.5em"></span>]
--accent-color: `#7952b3` (violet Bootstrap)Τα χαρακτηριστικά`role="img"` et `aria-label`επιτρέπουν στις τεχνολογίες βοήθειας να κατανοούν και να περιγράφουν το οπτικό περιεχόμενο.
Συγκεκριμένο παράδειγμα: Τεκμηρίωση θεμάτων
Αυτό είναι ένα πλήρες παράδειγμα που τεκμηριώνει πολλά θέματα :
= Guide des couleurs de l'application
== Thème Clair (`:root`)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)
== Thème Sombre (`[data-bs-theme="dark"]`)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #999;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#0d6efd;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#0d6efd` (bleu Bootstrap)
== Thème Contraste Élevé (`[data-bs-theme="high-contrast"]`)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#000000;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#000000` (noir)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #000;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#00ff00;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#00ff00` (vert vif)Συμπέρασμα
Έγχυση HTML μέσω του macro``Η AsciiDoc προσφέρει μια ελκυστική και πρακτική λύση για την εμφάνιση χρωματικών δειγμάτων στην τεχνική τεκμηρίωση. Αν και είναι ελαφρώς πλεοναστική, αυτή η προσέγγιση εξασφαλίζει τη μέγιστη μετακομικότητα και απλοποιημένη συντήρηση.
Αυτή η τεχνική δεν απαιτεί καμία εξωτερική ρύθμιση, καμία πρόσθετη φύλλο στυλ, και λειτουργεί αμέσως με το JBake και όλους τους τυπικούς επεξεργαστές AsciiDoc.
Αφού έχετε δημιουργήσει το πρώτο σας χρωματιστό τετράγωνο, απλώς αντιγράψτε-επικολλήστε τον HTML κώδικα και αλλάξτε τον δεκαεξαδικό κώδικα για να δημιουργήσετε γρήγορα μια πλήρη παλέτα.
Αυτή η τεχνική μπορεί να επεκταθεί σε άλλες περιπτώσεις χρήσης που απαιτούν προσαρμοσμένη οπτική παρουσίαση: εικονίδια, μπέιτζ, απλά γραφήματα ή οποιοδήποτε οπτικό στοιχείο που απαιτεί ακριβή έλεγχο του στυλ.
Πόροι
Άρθρο δημοσιεύτηκε το 2025-11-01