Εμφάνιση χρωματισμένων τετραγώνων σε AsciiDoc : Πρακτικός οδηγός
Publié le 01 November 2025
Εισαγωγή
Κατά τη σύνταξη τεχνικής τεκμηρίωσης, ειδικά για οδηγούς στυλ ή προδιαγραφές διεπαφής χρήστη, είναι συχνή η ανάγκη να εμφανίζονται παλέτες χρωμάτων. Το AsciiDoc, αν και πολύ ισχυρό για τεκμηρίωση, δεν προσφέρει ενδογενή σύνταξη για την εμφάνιση δείγμάτων χρωμάτων. Αυτό το άρθρο εξετάζει το πρόβλημα και προτείνει μια ελεγκτική λύση βασισμένη στην εγχέριση HTML.
Το ζήτημα
Περιβάλλον χρήσης
Φανταστείτε ότι τεκμηριώνετε τις μεταβλητές CSS ενός θέματος εφαρμογής ιστού. Χρειάζεστε:
-
Λίστα τα δεκαεξαδικά κώδικα χρώματος
-
Εμφάνιση οπτικής προespισκόπησης каждый χρώματος
-
διατήρηση της αναγνωσιμότητας του εγγράφου προέλευσης
-
Εξασφαλίστε τη συμβατότητα με τους δημιουργούς στατικών ιστοτόπων όπως το JBake
Οι δυνατές προσεγγίσεις
Υπολογίζονται διάφορες λύσεις για να εμφανιστούν χρώματα σε ένα έγγραφο AsciiDoc :
Επιλογή 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.
Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ] @startuml participant "Έγγραφο ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml participant "Έγγραφο AsciiDoc" as doc participant "Επεξεργαστής AsciiDoc" as processor participant "pass:[] μακροεντολή" as pass participant "HTML τελικό" 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Αρχιτεκτονική της λύσης
Πλεονεκτήματα και περιορισμοί
Πλεονεκτήματα
-
✓ 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