ການມາກອັບ AsciiDoc

ທີມງານເອກະສານ Fedora <https://discussion.fedoraproject.org/tag/docs-team> v1.0, 2022-12-10

ໜ້ານີ້ແບ່ງປັນຂໍ້ມູນທົ່ວໄປກ່ຽວກັບການຂຽນໃນ AsciiDoc ລວມທັງໄວຍາກອນສະເພາະຂອງ Fedora/Antora ທີ່ມັກພົບເຫັນເລື້ອຍໆໃນເອກະສານ Fedora.

ພື້ນຖານຂອງ AsciiDoc

AsciiDoc ແມ່ນພາສາມາກອັບນ້ຳໜັກເບົາສຳລັບຂຽນບັນທຶກ, ບົດຄວາມ, ເອກະສານ, ປຶ້ມ, ໜ້າເວັບ, ສະໄລ້ ແລະ ໜ້າ manual ໃນຮູບແບບຂໍ້ຄວາມທຳມະດາ.

— asciidoctor.org
ຄູ່ມືອ້າງອີງໄວຍາກອນ AsciiDoc ແບບດ່ວນ

ແຜ່ນລວມຄຳສັ່ງທີ່ສະດວກກ່ຽວກັບຮູບແບບການມາກອັບຂອງ AsciiDoc. ໃຊ້ສຳລັບການອ້າງອີງດ່ວນ ແລະ ກວດສອບວິທີການຈັດຮູບແບບ, ລາຍການ, ເນື້ອຫາສື່ (ຮູບພາບ ແລະ ວິດີໂອ), ສາລະບານ ແລະ ອື່ນໆ.

ແນວທາງການປະຕິບັດທີ່ແນະນຳຂອງ AsciiDoc

ແນວທາງທີ່ດີທີ່ສຸດກ່ຽວກັບການຂຽນໃນ AsciiDoc. ທີ່ສຳຄັນທີ່ສຸດ, ໃຫ້ຈື່ໄວ້ວ່າ ທຸກໆປະໂຫຍກຄວນຢູ່ແຖວໃຜແຖວມັນ.

ຂໍ້ຄວາມສັ້ນ (snippets) ຂອງເອກະສານ Fedora

ເມື່ອທ່ານຂຽນເອກະສານ Fedora, ບາງສິ່ງອາດຈະເກີດຂຶ້ນເລື້ອຍໆ. ພວກມັນອາດຈະບໍ່ໄດ້ຖືກບັນທຶກໄວ້ໃນເອກະສານ AsciiDoc ທົ່ວໄປ ຄືກັບຢູ່ໃນ asciidoctor.org. + ສ່ວນນີ້ປະກອບດ້ວຍຂໍ້ມູນອ້າງອີງທີ່ສະດວກສຳລັບຜູ້ຂຽນເອກະສານ Fedora ເພື່ອກ່າຍ ແລະ ວາງລົງໃນເອກະສານ AsciiDoc ຂອງຕົນເອງ.

ໃນສ່ວນນີ້, ພວກເຮົາຈະໃຊ້ໂຄງສ້າງຄັງເກັບ (repository) ຕໍ່ໄປນີ້ເປັນຕົວຢ່າງ:

ຕົວຢ່າງຂອງໂຄງສ້າງຄັງເກັບເອກະສານ
📄 antora.yml (1)
📂 modules
  📂 ROOT
    📂 pages
      📄 index.adoc
      📄 another-page.adoc
      📂 sub-dir
        📄 rules.adoc
  📂 council
    📂 pages
      📄 guiding-policy.adoc
1 ກຳນົດອົງປະກອບເອກະສານເປັນ test-module (ຄຸນລັກສະນະ name)

ຄັງເກັບດຽວກັນ

ໃຊ້ເສັ້ນທາງພາຍໃນທີ່ກ່ຽວຂ້ອງກັບໄດເຣັກທໍຣີ pages ໃນໂມດູນດຽວກັນ.

ລິ້ງໄປຫາໜ້າທີ່ຢູ່ໃນລະດັບ root
xref:another-page.adoc
ລິ້ງໄປຫາໜ້າໃນໄດເຣັກທໍຣີຍ່ອຍຂອງ pages
xref:sub-dir/rules.adoc

ຄືກັນກັບລິ້ງພາຍໃນ, ແຕ່ໃຫ້ໃຊ້ເຄື່ອງໝາຍຈ້ຳສອງເມັດ (:) ເພື່ອແຍກຊື່ໂມດູນ. ຖ້າທ່ານບໍ່ແນ່ໃຈວ່າຕ້ອງໃຊ້ສິ່ງນີ້ຫຼືບໍ່, ທ່ານອາດຈະບໍ່ຈຳເປັນຕ້ອງໃຊ້! ການລວມຫຼາຍໂມດູນໄວ້ໃນຄັງເກັບດຽວກັນ ແມ່ນຍັງບໍ່ທັນເປັນຮູບແບບທີ່ພົບເຫັນທົ່ວໄປໃນເອກະສານ Fedora.

ຕົວຢ່າງ 1
xref:council:guiding-policy.adoc

ລິ້ງໄປຫາໜ້າເອກະສານ Fedora ອື່ນທີ່ຢູ່ໃນຄັງເກັບອື່ນ. ໝາຍເຫດ: ທ່ານ ຕ້ອງ ໃຊ້ຟີລ name ທີ່ລະບຸໄວ້ໃນໄຟລ antora.yml ໃນຄັງເກັບອື່ນ ບໍ່ດັ່ງນັ້ນມັນຈະໃຊ້ວຽກບໍ່ໄດ້. ໃນກໍລະນີທີ່ຊື່ໂມດູນເປົ້າໝາຍແມ່ນ ROOT, ທ່ານສາມາດລະຊື່ໄດ້ ແຕ່ຍັງຕ້ອງມີເຄື່ອງໝາຍຈ້ຳສອງເມັດ (:) ເພີ່ມຕື່ມ.

ຕົວຢ່າງ 1, ທັງສອງລິ້ງແມ່ນມີຄ່າເທົ່າກັນ
xref:test-module::another-page.adoc
xref:test-module:ROOT:another-page.adoc
ຕົວຢ່າງ 2
xref:test-module:council:guiding-policy.adoc

ການປ່ຽນເສັ້ນທາງ URL (Redirects)

ທ່ານສາມາດສ້າງການປ່ຽນເສັ້ນທາງຈາກໜ້າເກົ່າໄປຫາໜ້າໃໝ່ໂດຍການໃຊ້ຄຸນລັກສະນະ page-aliases. ໄວຍາກອນແມ່ນຄືກັນກັບ ລິ້ງ xref.

ຕົວຢ່າງ 1. ໃນ new-page.adoc
= ຫົວຂໍ້ໜ້າ
:page-aliases: old-page.adoc

ທ່ານຍັງສາມາດສ້າງການປ່ຽນເສັ້ນທາງຈາກໂມດູນ ຫຼື ອົງປະກອບອື່ນໄດ້.

ຕົວຢ່າງ 2. ໃນ new-page.adoc
= ຫົວຂໍ້ໜ້າ
:page-aliases: test-module:council:removed-page.adoc

ການເນັ້ນໄວຍາກອນ (Syntax highlighting)

ທ່ານສາມາດເພີ່ມການເນັ້ນໄວຍາກອນໃຫ້ກັບບລັອກ source ໃດກໍໄດ້ ໂດຍການກຳນົດຄຸນລັກສະນະພາສາ source.

ຕົວຢ່າງຂອງການກຳນົດຄຸນລັກສະນະພາສາ source ໃຫ້ກັບບລັອກໂຄດ
[,yaml]
----
output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive
----
ຕົວຢ່າງຂອງບລັອກໂຄດທີ່ສະແດງຜົນດ້ວຍຄຸນລັກສະນະດັ່ງກ່າວ
output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive

ລາຍຊື່ພາສາທີ່ຮອງຮັບສາມາດເບິ່ງໄດ້ໃນ highlight.bundle.js ໃນ Fedora Docs UI.

ຕາຕະລາງຂໍ້ມູນ (Datatables)

ທ່ານສາມາດປ່ຽນຕາຕະລາງທຳມະດາໃຫ້ເປັນ DataTables ໂດຍການໃຊ້ຄຸນລັກສະນະ role datatable. DataTables ໃຫ້ຄວາມສາມາດໃນການກອງ ແລະ ຈັດລຽງຂໍ້ມູນ.

ຕົວຢ່າງຂອງການກຳນົດ 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%
|===

.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%

ສາມາດໃຊ້ role ເພີ່ມເຕີມເພື່ອເພີ່ມຄຸນສົມບັດຂອງ DataTables:

  • dt-search: ເພີ່ມຊ່ອງຄົ້ນຫາ

  • dt-paging: ເພີ່ມການແບ່ງໜ້າ

ທ່ານຍັງສາມາດປ່ຽນຮູບແບບໄດ້ດ້ວຍການຊ່ວຍເຫຼືອຈາກ ຄລາດ DataTables ທີ່ມີມາໃຫ້, ເຊັ່ນ display ຫຼື compact.

ຕົວຢ່າງຂອງການໃຊ້ຕົວເລືອກເພີ່ມເຕີມ
|===
[.datatable.dt-search.display]
|colA | colB | colC | colD

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

ການໃຊ້ງານ DataTables ຕົວຈິງສາມາດເບິ່ງໄດ້ທີ່ ເອກະສານທາງກົດໝາຍ.

ບລັອກແທັບ (Tabs block)

ທ່ານສາມາດສ້າງຊຸດແທັບເພື່ອຈັດລະບຽບເນື້ອໃນເອກະສານໃນບລັອກ.

ຕົວຢ່າງການກຳນົດຊຸດແທັບ [,asciidoc]
[tabs]
====
ແທັບ A:: ເນື້ອຫາຂອງແທັບ A.

ແທັບ B::
+
ເນື້ອຫາຂອງແທັບ B.

ແທັບ C::
+
--
ເນື້ອຫາຂອງແທັບ C.

ປະກອບມີຫຼາຍກວ່າໜຶ່ງບລັອກ.
--
====
ຊຸດແທັບທີ່ໄດ້

  • Tab A

  • Tab B

  • Tab C

ເນື້ອຫາຂອງແທັບ A.

ເນື້ອຫາຂອງແທັບ B.

ເນື້ອຫາຂອງແທັບ C.

ປະກອບມີຫຼາຍກວ່າໜຶ່ງບລັອກ.

ສຳລັບຂໍ້ມູນເພີ່ມເຕີມກ່ຽວກັບແທັບ, ໃຫ້ອ້າງອີງຈາກສ່ວນຂະຫຍາຍ Asciidoctor Tabs ທີ່ https://github.com/asciidoctor/asciidoctor-tabs.

ສາລະບານ

ສາລະບານຈະຖືກສ້າງຂຶ້ນໂດຍອັດຕະໂນມັດຢູ່ເບື້ອງຂວາຂອງແຕ່ລະໜ້າ.

ສຳຄັນ: ບໍ່ຈຳເປັນຕ້ອງເພີ່ມຄຸນລັກສະນະ :toc: ເພາະມັນຈະເຮັດໃຫ້ມີສາລະບານຊ້ຳຊ້ອນໃນເອກະສານ.

ສາລະບານເບື້ອງຂວາຈະສະແດງລະດັບຫົວຂໍ້ເຖິງລະດັບ 2 ເທົ່ານັ້ນໂດຍຄ່າເລີ່ມຕົ້ນ. ທ່ານສາມາດປ່ຽນຄ່ານີ້ໄດ້ດ້ວຍຄຸນລັກສະນະ page-toclevels.

= ຫົວຂໍ້ໜ້າ
:page-toclevels: 3

ການແບ່ງໜ້າ (Pagination)

ຖ້າທ່ານມີຫຼາຍໜ້າທີ່ເນື້ອຫາຕໍ່ເນື່ອງກັນ, ທ່ານອາດຈະສົນໃຈເປີດໃຊ້ການແບ່ງໜ້າ. + ການແບ່ງໜ້າຊ່ວຍໃຫ້ຜູ້ອ່ານສາມາດນຳທາງໄປຫາໜ້າຖັດໄປ ແລະ ໜ້າກ່ອນໜ້າໄດ້ຢ່າງງ່າຍດາຍຈາກຕົ້ນໄມ້ນຳທາງ ໂດຍການເພີ່ມລິ້ງນຳທາງຢູ່ທາງລຸ່ມຂອງໜ້າ.

ຕົວເລືອກນີ້ຖືກເປີດໃຊ້ໂດຍຄຸນລັກສະນະ page-pagination.

= ຫົວຂໍ້ໜ້າ
:page-pagination:

ທ່ານສາມາດເບິ່ງຕົວຢ່າງຈິງໄດ້ໃນໜ້ານີ້.

UI macro ສຳລັບປຸ່ມ ແລະ ເມນູ

ເພື່ອຮັກສາຄວາມສອດຄ່ອງໃນການສະແດງຜົນປຸ່ມ, ການກົດແປ້ນພິມ, ຫຼື ລາຍການເມນູ (ເສັ້ນທາງ), UI Macros ສຳລັບປຸ່ມ ແລະ ເມນູ ຈະຊ່ວຍບອກຜູ້ອ່ານວ່າພວກເຂົາຕ້ອງເຮັດຫຍັງແດ່.

ສຳຄັນ: ເຖິງແມ່ນວ່າຄຸນລັກສະນະນີ້ຈະຖືກຕັ້ງຊື່ວ່າ experimental (ທົດລອງ), ແຕ່ UI macros ຖືກຖືວ່າເປັນຟີເຈີທີ່ຄົງທີ່ຂອງ AsciiDoc ແລະ ຖືກນໍາໃຊ້ໃນ Quick Docs ທີ່ແກ້ໄຂຫຼ້າສຸດ.

ຕົວເລືອກນີ້ຖືກເປີດໃຊ້ໂດຍຄຸນລັກສະນະ experimental.

= ຫົວຂໍ້ໜ້າ
:experimental:

ຕົວຢ່າງການກຳນົດ Button UI Macro

. ຄລິກ btn:[Create].

. ເລືອກວະລີຜ່ານ (passphrase) ທີ່ແຂງແຮງ ແຕ່ກໍຈື່ຈຳໄດ້ງ່າຍໃນກ່ອງຂໍ້ຄວາມທີ່ສະແດງຂຶ້ນ.

. ຄລິກ btn:[OK] ແລ້ວຄີຈະຖືກສ້າງຂຶ້ນ.

ຕົວຢ່າງການກຳນົດ Menu UI Macro

ເພື່ອບັນທຶກໄຟລ, ໃຫ້ເລືອກ menu:File[Save].

ເລືອກ menu:View[Zoom > Reset] ເພື່ອຕັ້ງຄ່າລະດັບການຊູມຄືນໃໝ່ເປັນຄ່າເລີ່ມຕົ້ນ.

ແນວທາງການປະຕິບັດທີ່ດີທີ່ສຸດ

ຄຳແນະນຳບາງຢ່າງເມື່ອຂຽນໜ້າໃໝ່ ຫຼື ແກ້ໄຂໜ້າທີ່ມີຢູ່ແລ້ວ.

ສ່ວນຫົວຂອງເອກະສານ

ທຸກໆໜ້າ ຕ້ອງ ເລີ່ມຕົ້ນດ້ວຍຫົວຂໍ້ລະດັບ 1. [,asciidoc]

= ຫົວຂໍ້ໜ້າ

ທ່ານສາມາດເພີ່ມຂໍ້ມູນ meta ຂອງ ຜູ້ຂຽນ ແລະ ການກວດສອບ ໄດ້ຕາມຄວາມສະດວກ.

ຕົວຢ່າງ 1 - ຂໍ້ມູນຜູ້ຂຽນ ແລະ ການປັບປຸງ
= ຫົວຂໍ້ໜ້າ
Ben Cotton; Peter Boy; Petr Bokoc 2.0, 2022-11-26: ແກ້ໄຂສຳລັບ F37

ທ່ານສາມາດເລືອກທີ່ຈະລະເລກເວີຊັນໄດ້ ຖ້າທ່ານບໍ່ຕ້ອງການຂໍ້ມູນນັ້ນ.

ຕົວຢ່າງ 2 - ຂໍ້ມູນການປັບປຸງໂດຍບໍ່ມີເວີຊັນ
= ຫົວຂໍ້ໜ້າ
Francois Andrieu 2022-12-10: ເພີ່ມຕົວຢ່າງຂໍ້ມູນ meta ການປັບປຸງ

ເຖິງແມ່ນວ່າຂໍ້ມູນ meta ເຫຼົ່ານີ້ຈະເປັນທາງເລືອກ, ແຕ່ໃຫ້ພະຍາຍາມຮັກສາຢ່າງໜ້ອຍວັນທີປັບປຸງ ເພື່ອໃຫ້ຜູ້ອ່ານຮູ້ວ່າໜ້ານີ້ທັນສະໄໝພໍໃດ.

ຕົວຢ່າງ 3 - ວັນທີປັບປຸງເທົ່ານັ້ນ
= ຫົວຂໍ້ໜ້າ
ທີມງານເອກະສານ Fedora 2022-12-10

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