Egenverk Docs Viewer · Dokumentation
Läsvyn
Läsvyn finns under Verktyg → Docs Viewer och är byggd som en repo-sida på GitHub: filträd till vänster, dokumentet till höger.
Vad som skannas
Docs Viewer går igenom:
- tillägg som ligger i en egen mapp i
wp-content/plugins - alla installerade teman, i
wp-content/themesoch i andra registrerade temamappar - must-use-tillägg som ligger i en egen mapp under
wp-content/mu-plugins
I varje mapp tas följande med:
| Plats | Filer |
|---|---|
| Mappens rot | .md, .markdown, .mdown och .txt, till exempel README.md, CHANGELOG.md och readme.txt |
docs/ och dess undermappar | Samma format plus .json, .js, .jsx, .ts, .tsx, .css, .scss, .less, .html, .htm, .xml, .yml, .yaml, .ini och .conf |
PHP-filer listas och läses aldrig. I docs/ hoppas mapparna node_modules, vendor, .git, bin och build över, och skanningen går högst åtta nivåer ner i undermappar. Mappar utan några sådana filer visas inte. Docs Viewers egen mapp skannas inte.
Indexet byggs om automatiskt när tillägg eller teman installeras, uppdateras eller tas bort, och när tillägg aktiveras eller inaktiveras. Efter ändringar utanför WordPress klickar du på Scan for docs. Efter en skanning visar en statusetikett, till exempel Scanned — 12 found, hur många tillägg och teman med dokumentation som hittades.
Läsvyns delar
| Del | Vad den gör |
|---|---|
| Toppfältet | Väljaren för tillägg och teman, sökfältet Search all docs och knappen Scan for docs |
| Files | Filerna i det valda tillägget, rotfilerna först och sedan mapparna i docs/. Rutan Filter files… döljer filer vars namn inte matchar |
| On this page | Dokumentets rubriker på nivå 2–3, eller 1–3 om dokumentet saknar nivå 2. Klicka för att hoppa dit. Visas när det finns minst två |
| Preview | Det formaterade Markdown-dokumentet. För andra filer heter fliken Rendered |
| Raw | Källtexten oförändrad, med knappen Copy |
Väljaren visas när mer än ett tillägg eller tema har dokumentation. Finns fler än en sort grupperas den under Plugins, Themes och Must-use plugins. När du öppnar ett tillägg visas dess README först, om det har en.
Inga adminmeddelanden visas på läsvyns sida, så att de inte hamnar mitt i dokumentet. På övriga adminsidor visas de som vanligt.
Formatering
Markdown-filer och .txt-filer i wordpress.org-formatet för readme.txt visas formaterade. Andra filer visas som kod och körs aldrig.
Formateraren klarar det som tilläggsdokumentation brukar använda:
- rubriker, fetstil, kursiv och genomstruken text
- listor, även nästlade
- tabeller med vänster-, höger- och centrerad justering
- citatblock
- länkar, bilder och fristående webbadresser
- horisontella linjer
- kod i löptext och kodblock
Kodblock färgas för PHP, JavaScript, TypeScript, JSX, TSX, JSON, CSS, SCSS, HTML/XML, shell, YAML, SQL, diff och INI. Färgningen följer med tillägget och hämtar inget utifrån. Raw visas alltid utan färgning.
Det här stöds inte: rå HTML i dokumentet (visas som text, körs aldrig), referenslänkar, fotnoter och rubriker som understryks med === eller ---.
Länkar och bilder i dokument
Relativa länkar fungerar som på GitHub. En länk till ett annat dokument i samma tillägg, eller till en mapp med en README, öppnas i läsvyn. Länkar till en rubrik i ett annat dokument öppnas vid rubriken.
Relativa bilder visas när de ligger inuti tilläggets egen mapp och är .png, .jpg, .jpeg, .gif, .webp eller .svg. En relativ länk som inte pekar på ett skannat dokument visas som vanlig text, och en bild som inte uppfyller villkoren visas som sin alt-text.
Sök
Skriv minst två tecken i Search all docs och tryck Enter. Sökningen går igenom varje skannat dokument i alla tillägg, teman och must-use-tillägg och skiljer inte på stora och små bokstäver. Frågan matchas precis som du skriver den, så även tecken som <div eller %20 går att hitta. Fältet tar högst 100 tecken.
Träffarna visar tillägg och fil, med upp till tre markerade rader per fil. Klicka på en träff för att öppna filen, eller på Close search för att gå tillbaka till dokumentet. Högst 100 filer listas; då står det Showing the first 100 files. Refine the search to see more. och du gör frågan smalare.
Länkar på Tillägg-sidan
Tillägg med dokumentation får länkar på sin rad på sidan Tillägg:
| Länk | Vad den gör |
|---|---|
| What’s new in X.Y | Visas efter en uppdatering. Öppnar ändringsloggen kapad till versionerna sedan den du hade |
| View Docs | Öppnar tilläggets dokumentation i läsvyn |
| Changelog | Öppnar tilläggets CHANGELOG i roten, annars dess readme.txt, vid avsnittet för den installerade versionen, eller vid rubriken Changelog när inget avsnitt matchar. Visas bara när tillägget har en sådan fil |
Docs Viewers egen rad har dessutom länken Browse Docs, som öppnar läsvyn.
What’s new kräver en CHANGELOG i Markdown (.md, .markdown eller .mdown) eller en readme.txt i roten. Den kapade loggen visas under en ruta med texten What’s new since följt av versionerna och länken Show the full changelog. Länken försvinner för alla när en administratör har öppnat den, och annars efter 30 dagar. Uppdateras tillägget igen innan någon har läst, visas båda versionernas ändringar. Bara tillägg följs, inte teman eller must-use-tillägg.
Länkarna är påslagna som standard. För att ta bort dem för ett tillägg: öppna tillägget i läsvyn och slå av Show “View Docs” link on the Plugins page i sidofältet. Ändringen sparas direkt och tar bort alla tre länkarna för det tillägget. Inställningen finns bara för tillägg, eftersom teman och must-use-tillägg inte har någon rad på Tillägg-sidan. Bara administratörer ser och ändrar den.
Länkarna visas bara för användare som får öppna läsvyn, och bara på webbplatsens egen Tillägg-sida, inte i nätverksadmin.