Σήμανση AsciiDoc

Ομάδα τεκμηρίωσης Fedora <https://discussion.fedoraproject.org/tag/docs-team> v1.0, 10/12/2022

Αυτή η σελίδα παρέχει γενικές πληροφορίες σχετικά με τη συγγραφή σε AsciiDoc, καθώς και συγκεκριμένα χαρακτηριστικά σύνταξης του Fedora/Antora που εμφανίζονται συχνά στην τεκμηρίωση του Fedora.

Βασικά στοιχεία της AsciiDoc

Η AsciiDoc είναι μια «ελαφριά» γλώσσα σήμανσης για σημειώσεις, άρθρα, τεκμηρίωση, βιβλία, ιστοσελίδες, παρουσιάσεις και σελίδες man με απλό κείμενο.

— asciidoctor.org
Γρήγορη αναφορά στη σύνταξη της AsciiDoc

Ένας πρακτικός οδηγός σχετικά με την εμφάνιση της σήμανσης AsciiDoc. Χρησιμοποιήστε τον για γρήγορες αναφορές και ελέγχους σχετικά με μορφοποιήσεις, λίστες, περιεχόμενο πολυμέσων (εικόνες και βίντεο), πίνακες περιεχομένων κ.α.

Προτεινόμενες πρακτικές για την AsciiDoc

Οι βέλτιστες πρακτικές σχετικά με τη συγγραφή σε AsciiDoc. Είναι πολύ σημαντικό να σημειώσουμε ότι κάθε πρόταση θα πρέπει να είναι στη δική της γραμμή.

Αποσπάσματα τεκμηρίωσης Fedora

Όταν γράφετε τεκμηρίωση για το Fedora, κάποια πράγματα εμφανίζονται συχνά. Αυτά ενδέχεται να μην περιγράφονται στη γενική τεκμηρίωση της AsciiDoc, όπως στο asciidoctor.org. + Αυτή η ενότητα περιέχει χρήσιμες αναφορές που οι συντάκτες τεκμηρίωσης του Fedora μπορούν να αντιγράψουν και να επικολλήσουν στα δικά τους έγγραφα AsciiDoc.

Σε αυτήν την ενότητα, θα χρησιμοποιήσουμε ως παράδειγμα την ακόλουθη δομή αποθετηρίου:

Παράδειγμα δομής αποθετηρίου τεκμηρίωσης
📄 antora.yml (1)
📂 modules
  📂 ROOT
    📂 pages
      📄 index.adoc
      📄 another-page.adoc
      📂 sub-dir
        📄 rules.adoc
  📂 council
    📂 pages
      📄 guiding-policy.adoc
1 Ορίζει το στοιχείο τεκμηρίωσης ως test-module (ιδιότητα name)

Ίδιο αποθετήριο

Use the local path relative to the pages directory in the same module.

Σύνδεσμος προς σελίδα στο επίπεδο ρίζας
xref:another-page.adoc
Σύνδεσμος προς σελίδα σε έναν υποκατάλογο του pages
xref:sub-dir/rules.adoc

Like an internal link, but use a colon (:) to separate the module name. If you are not sure if you need this, you likely don’t! Multiple modules bundled in the same repository is not currently a common scenario in Fedora Documentation.

Παράδειγμα 1
xref:council:guiding-policy.adoc

Link to another Fedora Documentation page that exists in another repository. Note that you must use the name field specified in the antora.yml file in the other repository or it will not work. In case the target module name is ROOT, you can omit the name but you still need the extra colon (:).

Example 1, both links are equivalent
xref:test-module::another-page.adoc
xref:test-module:ROOT:another-page.adoc
Παράδειγμα 2
xref:test-module:council:guiding-policy.adoc

Ανακατευθύνσεις URL

Μπορείτε να δημιουργήσετε μια ανακατεύθυνση από μια παλιά σελίδα σε μια νέα χρησιμοποιώντας την ιδιότητα page-aliases. Η σύνταξη είναι όμοια με αυτή για το xref links.

Παράδειγμα 1: Στο new-page.adoc
= Τίτλος σελίδας
:page-aliases: old-page.adoc

You can also create a redirect from another module or component.

Example 2. In new-page.adoc
= Τίτλος σελίδας
:page-aliases: test-module:council:removed-page.adoc

Επισήμανση σύνταξης

You can add syntax highlighting to any source block by setting the source language attribute.

Example of setting the source language attribute to a code block
[,yaml]
----
output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive
----
Example of rendered code block with such attribute
output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive

The list of supported languages can be found in the highlight.bundle.js in the Fedora Docs UI.

Πίνακες δεδομένων

You can convert a regular table to a DataTables using the datatable role attribute. DataTables provides filtering and ordering capabilities.

Example of defining a DataTable
|===
[.datatable]
|colA | colB | colC | colD

| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
| ccc | 9 | ttt | 2%
| aaa | 987 | www | 18%
|===

.Rendered DataTable [.datatable]

colA

colB

colC

colD

yyy

123

zzz

28%

bbb

242

aaa

42%

ddd

8874

yyy

99%

ccc

9

ttt

2%

aaa

987

www

18%

Additional roles can be used to add DataTables features:

  • dt-search: add search box

  • dt-paging: add pagination

You can also alter the styling with the help of built-in DataTables classes, such as display or compact.

Example of using additional options
|===
[.datatable.dt-search.display]
|colA | colB | colC | colD

| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
|===

DataTables real usage can be seen on the Legal documentation.

Tabs block

You can create a set of tabs to organize documentation content in a block.

Example of defining a tab set [,asciidoc]
[tabs]
====
Καρτέλα Α:: Περιεχόμενα της Καρτέλας Α.

Καρτέλα Β::
+
Περιεχόμενα της Καρτέλας Β.

Καρτέλα Γ::
+
--
Περιεχόμενα της Καρτέλας Γ.

Περιέχει περισσότερα από ένα μπλοκ.
--
====
Resulting tab set

  • Tab A

  • Tab B

  • Καρτέλα Γ

Contents of Tab A.

Contents of Tab B.

Περιεχόμενα της Καρτέλας Γ.

Περιέχει περισσότερα από ένα μπλοκ.

For more information about tabs, refer to the Asciidoctor Tabs extension at https://github.com/asciidoctor/asciidoctor-tabs.

Πίνακας περιεχομένων

A table of content is automatically generated on the right of each pages.

There is no need to add the :toc: attribute as it will then add a duplicate table of content to the document.

The right-sided table of content only displays title levels up to level 2 by default. You can change this setting with the page-toclevels attribute.

= Τίτλος σελίδας
:page-toclevels: 3

Σελιδοποίηση

If you have several pages that follow the same topic, you might be interested in enabling the pagination. + Pagination allows the reader to easily navigate to next and previous pages from the navigation tree by adding navigation links at the bottom of the page.

This option is enabled by the page-pagination attribute.

= Τίτλος σελίδας
:page-pagination:

You can see a live example on this page.

Button and Menu UI macro

To keep consistency in presenting a button, keyboard bindings, or a menu item (path), Button and Menu UI Macros communicate to the reader what actions they need to take.

Although this attribute is named experimental, the UI macros are considered a stable feature of the AsciiDoc and used in latest Quick Docs edited.

This option is enabled by the experimental attribute.

= Τίτλος σελίδας
:experimental:

Examples of defining Button UI Macro

. Κάντε κλικ στο btn:[Δημιουργία].

. Choose a passphrase that is strong but also easy to remember in the dialog that is displayed.

. Click btn:[OK] and the key is created.

Examples of defining Menu UI Macro

To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

Βέλτιστες πρακτικές

Ακολουθούν ορισμένες προτάσεις για τη σύνταξη μιας νέας σελίδας ή την επεξεργασία μιας υπάρχουσας.

Επικεφαλίδα εγγράφου

Όλες οι σελίδες πρέπει να ξεκινούν με τίτλο επιπέδου 1. [,asciidoc]

= Τίτλος σελίδας

Μπορείτε, προαιρετικά, να προσθέσετε μεταδεδομένα συντακτών και αξιολογήσεων.

Παράδειγμα 1: Πληροφορίες συντακτών και αναθεώρησης
= Τίτλος σελίδας
Ben Cotton; Peter Boy; Petr Bokoc 2.0, 26/11/2022: διόρθωση για το F37

Μπορείτε να παραλείψετε τον αριθμό έκδοσης αν δεν έχετε αυτήν την πληροφορία.

Παράδειγμα 2: Πληροφορίες αναθεώρησης χωρίς έκδοση
= Τίτλος σελίδας
Francois Andrieu 10/12/2022: Προστέθηκε παράδειγμα μεταδεδομένων αναθεώρησης

While these metadata are optional, try to keep at least the revision date so readers know how up-to-date the page is.

Παράδειγμα 3: Μόνο ημερομηνία αναθεώρησης
= Τίτλος σελίδας
Ομάδα τεκμηρίωσης Fedora 10/12/2022

Want to help? Learn how to contribute to Fedora Docs ›