Cum să construiți o bază de cunoștințe de asistență prietenoasă cu SEO: Ghidul complet pentru o soluție de documentare scalabilă

Publicat: 2016-10-26

Odată ce baza de utilizatori a startup-ului tău crește, asistența devine o parte fundamentală a afacerii tale. Crearea unei soluții solide de bază de cunoștințe este o investiție importantă pe termen lung, care sperăm că, dacă este făcută corect, va da roade prin reducerea sarcinii de suport, extinderea acoperirii SEO a site-ului dvs. și generarea de noi clienți potențiali care altfel nu ar fi fost atinși.

Acesta este un ghid cuprinzător și tehnic pas cu pas pentru dezvoltatori. Dacă nu sunteți dezvoltator, probabil că ar trebui să trimiteți acest articol către CTO. El/ea vă va mulțumi pentru asta.

TL;DR: Am construit și lansat în sfârșit baza noastră de cunoștințe semistatică, bazată pe reduceri, pentru platforma noastră de monetizare Freemius, folosind WordPress. Împărtășesc cartea completă de bucate a cercetării noastre chiar aici; de ce alegem WordPress în locul soluțiilor SaaS și generatoarelor statice; cum am făcut-o (inclusiv toate personalizările codului și configurația la nivel de server), ce am învățat și cum puteți replica acel proces pentru a economisi timp prețios și pentru a vă configura propriul dvs. rapid, scalabil, durabil, sigur și semi- KB static (Baza de cunoștințe) pentru propriul plugin, temă sau orice alt produs digital.

Acest ghid de 15 minute vă va economisi 44 de ore (am folosit urmărirea timpului) de cercetare, personalizare, testare și optimizare. Dacă încă nu sunteți la etapa de creare a propriului centru de documentare, doar marcați această pagină și reveniți când este momentul potrivit.

Sunteți gata? Începem.

Motivația
Ce ar trebui să cauți într-o soluție de documentare?
1. Scalabil și durabil
2. Back Office ușor de utilizat
3. Durabil
4. Optimizat SEO
5. Compatibil cu marca
Este dificil să alegi platforma de documentare potrivită!
- Baza de cunoștințe Software ca serviciu
- Baze de cunoștințe statice
- Baze de cunoștințe bazate pe WordPress
De ce nu am ales Help Scout Docs sau orice altă bază de cunoștințe SaaSy
De ce alegem WordPress în locul generatoarelor statice de site pentru baza noastră de cunoștințe
De ce alegem pluginul WordPress weDocs pentru baza noastră de cunoștințe?
Instalarea și personalizarea soluției de documentare weDocs
- Adăugarea metadatelor de fragmente îmbogățite de breadcrumbs
- Personalizarea structurii URL a bazei de cunoștințe (permalink-uri)
- Adăugarea unei pagini de pornire drăguță la baza de cunoștințe weDocs
- Faceți weDocs Mobile friendly / receptiv
Folosind Markdown în loc de HTML Rich Editing
- Alegerea și instalarea unui plugin WordPress Markdown
- Adăugarea suportului pentru YouTube și Vimeo Markdown
- Adăugarea de asistență pentru coduri scurte pentru înștiințări frumoase
- Adăugarea SyntaxHighlighter pentru Pretty Code
Cum am făcut baza noastră de cunoștințe WordPress super rapidă?
- Adăugarea permisiunilor de disc
- Activarea memoriei cache
- Configurarea memoriei cache la nivel de server
- Adăugarea CDN-ului
Cum am personalizat căutarea KB pentru a servi date din cache?
Cum ne-am asigurat baza de cunoștințe WordPress?
Acum tu

Motivația

Documentația a fost întotdeauna pe lista noastră de TODO încă de la începuturile lui Freemius. Acestea fiind spuse, atunci când produsul este în stadii incipiente, nu are sens să te grăbești și să-l documentezi. Accentul ar trebui să se concentreze pe validarea ipotezelor și iterațiile rapide, până când ajungeți la o potrivire satisfăcătoare a produsului-piață. Am început Freemius în urmă cu aproximativ un an și jumătate și, în sfârșit, am simțit că este timpul să acordăm prioritate documentației.

Ce ar trebui să cauți într-o soluție de documentare?

Înainte să mă grăbesc într-o soluție, am vrut să am un fel de plan. Prin urmare, am creat următoarea listă de cerințe:

Scalabil și durabil

Ca orice altă soluție bazată pe web, trebuie să fie capabilă să se adapteze traficului nostru, menținând în același timp aceeași performanță. De asemenea, TREBUIE să continue să fie fără efort pentru a găsi răspunsuri atunci când baza de cunoștințe crește dincolo de o duzină de articole. Cu alte cuvinte – căutare bună!

Back Office ușor de utilizat

Adăugarea și editarea articolelor de documentare ar trebui să fie ușoară pentru orice membru al echipei, indiferent dacă este sau nu dezvoltatori.

Durabil

Nimic nu ține la nesfârșit. Tendințele în design se schimbă, iar tehnologia evoluează tot timpul. Prin urmare, ar trebui să fie relativ ușor să modificați interfața de utilizare a bazei de cunoștințe și, în cazuri extreme, să exportați cu ușurință datele și să migrați într-un sistem complet diferit.

Optimizat SEO

Documentația este conținut. Spre deosebire de postările de pe blog, documentația din baza de cunoștințe se concentrează exclusiv pe produsul dvs. Cuvintele tale cheie. Este o modalitate excelentă de a vă împuternici autoritatea SEO în orice vindeți.

În plus, atunci când utilizatorii caută ceva, obiceiul comun este să folosească un motor de căutare imediat. Este mai ușor decât să vă deschideți site-ul, să căutați linkul Baza de cunoștințe / Centrul de ajutor / Documente și abia apoi să căutați o soluție. Prin urmare, mai bine vă asigurați că conținutul documentației este vizibil pentru motoarele de căutare și este optimizat pentru acestea, în special pentru Google, dacă vizați piața vorbitoare de limba engleză.

Compatibil cu marca

Aspectul și senzația bazei de cunoștințe ar trebui să se potrivească cu limbajul de design și branding-ul companiei noastre. Acestea includ culorile, fonturile, stilul antetului și subsolului etc.

Este dificil să alegi platforma de documentare potrivită!

Urmând fluxul meu natural de descoperire, m-am dus să cer sfaturi Google. De data aceasta, Google nu a fost de ajutor. Rezultatele căutării au fost copleșitoare. Nu numai că există atât de multe opțiuni pe piață, dar soluțiile sunt în mod inerent diferite.

Google nu a fost de ajutor. Există atât de multe opțiuni pe piață și soluțiile sunt în mod inerent diferite. Tweet

Baza de cunoștințe Software ca serviciu

Există soluții software de bază de cunoștințe desemnate alimentate de companii de birou de asistență, cum ar fi Help Scout Docs și Centrul de ajutor Zendesk.

Baze de cunoștințe statice

Generatoarele statice de site devin din ce în ce mai populare. Dacă nu sunteți familiarizat cu conceptul, ideea generală este că cele mai multe site-uri web sunt destul de statice (inclusiv blogul dvs. WordPress) și nu există niciun motiv real pentru a rula o stivă de backend epuizantă precum WordPress / PHP / MySql. În schimb, mutarea sarcinilor grele la un motor de pre-implementare care va genera pagini HTML statice care pot fi găzduite pe CDN-uri fără să vă atingeți măcar serverele. Este rentabil, scalabil și sigur.

Există sute de generatoare acolo, iar motoarele precum Jekyll și Hugo sunt foarte populare în rândul comunității de dezvoltatori hardcore (dintr-un motiv bun!).

Baze de cunoștințe bazate pe WordPress

Am găsit peste 20 de pluginuri gratuite de bază de cunoștințe în depozitul WordPress.org, încă o duzină de pluginuri de documentare plătite pe CodeCanyon și Google și încă o duzină de teme din Centrul de ajutor.

Simțindu-se confuz? Cu siguranță am făcut ¯\(°_o)/¯

După cum puteți vedea, mult prea multe opțiuni. Am decis să încerc o altă strategie – cerând o recomandare de la oameni în care părerea am încredere. Sunt membru al unui grup Facebook numit Vânzarea de produse WordPress, din care fac parte mulți dintre prietenii mei și oameni de top din produse WordPress. Sunt destul de sigur că 90% dintre ei s-au confruntat cu aceeași provocare înaintea mea, așa că a meritat cu siguranță încercarea.

Înainte de a încărca întrebarea mea, am căutat puțin și am găsit un thread din 2015, început de Jean Galea de la WP Mayor, care pune exact aceeași întrebare:

Minunat! M-am gândit. Și apoi am început să citesc răspunsurile...

Adrian Labos folosește Zendesk Help Desk
Pippin Williamson (Pippin Plugins) și Adam Pickering (Astoundify) folosesc Help Scout Docs
Phil Derksen folosește WordPress cu tema KnowHow
Dejan Markovic (Hype Social) folosește WordPress cu pluginul weDocs
Devin Walker (WordImpress) folosește WordPress cu CPT și pluginul ACF.
Ahmad Awais, care a creat tema DocPress, spune că „menținerea unui site de documente cu WordPress a devenit ineficientă atunci când numărul de produse crește” și acum construiește o bază de cunoștințe statică cu motorul de șabloane Jade.
Tom Hemsley (pluginul Mega Menu) a recomandat utilizarea WordPress cu pluginul Heroic Knowledge Base.
Au existat alte trei răspunsuri despre pluginuri WordPress suplimentare de la autorii lor care fac parte din grup.

După cum puteți vedea, pur și simplu nu există un consens. Din păcate, acest lucru nu a fost de mare ajutor.

La naiba – este timpul pentru niște cercetări…

SFAT: Ca o notă secundară, dacă sunteți o persoană de produs în sfera WordPress, vă recomand cu căldură să aplicați pentru acest grup.

Abonați-vă și obțineți o copie gratuită a documentului nostru

Cartea de afaceri cu pluginul WordPress

Exact cum să creezi o afacere prosperă cu pluginuri WordPress în economia abonamentului.

Multumesc pentru abonare!

- tocmai v-am trimis copia „The WordPress Plugin Business Book” către .

Ai o greșeală de scriere în e-mail? faceți clic aici pentru a edita adresa de e-mail și a trimite din nou.

De ce nu am ales Help Scout Docs sau orice altă bază de cunoștințe SaaSy

Sunt un fan al Help Scout și îi folosim pentru sistemul nostru de ticketing de asistență. De fapt, sunt prieten cu fondatorii. În 2011, am lucrat la biroul 2 și am stat împreună timp de 4 luni, în timp ce participam la programul de accelerare Techstars din Boston. Asta a fost atunci când Help Scout era doar Denny, Jared și Nick.

Docs este o soluție de documentare destul de solidă și probabil cea mai simplă și rapidă cale de a parcurge. De asemenea, este surprinzător de personalizabil. Dar, ca și celelalte platforme SaaS, vine cu defecte SEO.

1. Configurarea unei baze de cunoștințe sau a oricărui alt conținut într-un subdirector este în continuare semnificativ mai bună decât pe un subdomeniu în ceea ce privește clasarea căutării. Rand Fishkin, fondatorul MOZ (cea mai mare companie SEO din lume) are un videoclip grozav din 2015 cu cazuri reale de utilizare care discută acest subiect.

Din păcate, din cauza modului în care funcționează fișierele DNS Zone, nu există nicio modalitate de a configura un CNAME într-un subdirector.

Pentru a mă asigura că nu am ratat nicio soluție, am contactat echipa de asistență Help Scout și iată răspunsul pe care l-am primit:

„Urăsc să vin cu vești proaste, dar nu există o modalitate de a avea Docs într-un subdirector. Avem un API pentru Documente care vă permite să vă exportați site-ul și să-l găzduiți singur, dar va trebui să reconstruiți o parte din aspectul și funcționalitatea: http://developer.helpscout.net/docs-api/
Mă tem că aceasta ar fi singura soluție dacă ați dori în continuare să utilizați Docs și să-l aveți ca subdirector.

2. Nu am verificat celelalte soluții din motivul anterior, dar Help Scout Docs , în special, nu include metadate Rich-Snippets pentru breadcrumbs și căutare.

Așa arată un rezultat din Help Scout Docs pe SERP (pagina cu rezultate ale motorului de căutare) Google:

Iată un rezultat al unei pagini care are metadate pentru fragmente de pană bogate:

Și iată un rezultat al unei pagini care conține metadate ale fragmentelor îmbogățite de căutare:

Nu voi aprofunda acest subiect, dar, în general, metadatele fragmentelor îmbogățite ajută motorul de căutare să înțeleagă mai bine conținutul site-ului și structura acestuia. Cele mai importante motoare de căutare din lume: Google, Yahoo și Bing; poate traduce aceste date în elemente vizuale care măresc CTR (rata de clic) în căutare. Concluzie – veți obține mai mult trafic.

De asemenea, l-am sunat pe Chris Mooney, un co-fondator la HeroThemes, o companie care se concentrează singur pe soluțiile de bază de cunoștințe, și a confirmat că SEO este unul dintre principalele motive pentru care clienții migrează la soluția lor de documentare on-prem.

Doar pentru a sublinia importanța valorii SEO pe care o puteți obține dintr-o documentație bine scrisă, aș dori să vă împărtășesc o poveste rapidă. În 2011, m-am întâlnit cu Elad Eran, VP Customer Solutions la WiX. Eran a explicat cu mândrie că software-ul din baza de cunoștințe și forumurile de asistență sunt unul dintre principalii catalizatori care au ajutat WiX să se claseze pe Google și să obțină trafic organic gratuit, de înaltă calitate.

Software-ul bazei de cunoștințe și forumurile de asistență sunt unul dintre principalii catalizatori care au ajutat WiX să se claseze înalt pe Google și să obțină trafic organic gratuit, de înaltă calitate.Tweet

Dacă este bun pentru WiX, ar trebui să fie bun pentru noi

De ce alegem WordPress în locul generatoarelor statice de site pentru baza noastră de cunoștințe

Principalele beneficii ale devenirii statice cu un motor precum Jekyll sunt viteza, scalabilitatea și securitatea.

Le putem obține cu WordPress? Răspunsul este – aproape.

Deoarece paginile de documentație sunt statice (cu excepția căutării), putem instala cu ușurință unul dintre zecile de pluginuri gratuite de cache pentru WordPress, putem configura Nginx pentru a servi fișierele stocate în cache direct de pe disc, în timp ce omitem motorul WordPress și, de asemenea, folosim un serviciu CDN gratuit precum CloudFlare pentru a ne distribui fișierele în diferite centre de date de pe tot globul. S-ar putea să sune complex, dar chiar nu este, și voi explica totul în curând.

Acest lucru va transforma documentația noastră în frontend-ul absolut static. Se va scala grozav și va fi super-rapid (pentru că este static). W00t! W00t!

În ceea ce privește securitatea, nimic nu este perfect. Dar, putem lua câteva măsuri de precauție de bază folosind câteva plugin-uri gratuite și câteva configurații la nivel de server, care vor reduce șansa de atac cu 99,9%. Voi discuta în mod explicit despre asta, incluzând toate ingredientele.

Pe de altă parte, dezavantajele abordării statice pentru echipa noastră au fost:

Ca echipă, va trebui să dobândim un nou set de abilități tehnice, să creăm un mediu de dezvoltare suplimentar și să avem un proces de implementare continuă pentru a ne asigura că adăugarea sau editarea fișierelor nu necesită intervenția unui dezvoltator. Cu siguranță este realizabil, dar este nevoie de timp.
Căutarea este (în cea mai mare parte) o funcționalitate dinamică, așa că dacă mergem statici, va trebui să implementăm un API RESTful sau să integrăm un serviciu de căutare terță parte precum Algolia. Încă o durere de cap cu care să faci față.
Controlul versiunilor nu este un CMS. Oricât de mult îmi plac GitHub și BitBucket, ar putea fi înfricoșătoare pentru cei care nu cunosc tehnologie. Chiar dacă toți membrii echipei noastre sunt dezvoltatori în trecut, acest lucru este probabil să se schimbe în viitor.

SFAT: Merită menționat că în timpul cercetării mele am găsit un proiect ingenios numit Prose.io care oferă o editare simplă de conținut WYSIWYG a fișierelor GitHub și BitBucket.

Pentru a rezuma, putem obține cele mai multe dintre beneficiile site-urilor statice fără a pierde flexibilitatea WordPress, păstrând editorul CMS ușor de utilizat și obținând editare în timp real fără un proces continuu de implementare.

De ce alegem pluginul WordPress weDocs pentru baza noastră de cunoștințe?

După cum am menționat anterior, am văzut cel puțin 30 de plugin-uri și teme WordPress pentru bazele de cunoștințe.

Deoarece derulăm o pornire, evaluarea tuturor acestora nu este fezabilă. Deci să încercăm să mergem cu eliminarea.

Temele din baza de cunoștințe au apărut!

Am ales să nu mergem cu nicio temă de documentare, deoarece majoritatea dintre ele folosesc taxonomia implicită a obiectelor de post și category pentru articolele de documentare. Această soluție poate funcționa dacă configurați o instanță WordPress dedicată doar pentru aplicația dvs. de bază de cunoștințe. Dacă doriți să aveți tot site-ul dvs. pe aceeași instalare WordPress, inclusiv blogul dvs., lucrurile se pot încurca și probabil se vor încurca din cauza amestecului de tipuri de conținut.

Da – acum avem doar alte 20 de plugin-uri de testat...

Am testat patru pluginuri gratuite diferite:

Baza de cunoștințe CPT
Baza de cunoștințe WP
Ajutor WP
weDocs

Destul de repede am descoperit că toate folosesc WordPress CPT (Custom Post Types) și taxonomia personalizată pentru etichete și categorii. Principala și singura diferență semnificativă este în ierarhia structurii datelor.

Baza de cunoștințe CPT și WP Baza de cunoștințe sunt plate. Ca și în cazul postărilor pe blog, există categorii, etichete și articole. Nu există nicio modalitate de a asocia un articol cu un articol părinte.

Deci, structura unei baze de cunoștințe cu aceste plugin-uri va fi categorii ca secțiuni și postări ca documente.

 Categoria 1
↳ Doc 1
↳ Doc 2

Categoria 2
↳ Doc 3
↳ Doc 4

Avantajul acestei structuri este că puteți asocia un document cu mai multe categorii și îl puteți face să apară în mai multe secțiuni.

 Categoria 1
↳ Doc 1
...
Categoria 2
↳ Doc 3
↳ Doc 1

Pe de altă parte, structura de articole WP Help și weDocs este similară cu paginile. Fiecare document poate fi asociat cu orice alt document ca părinte. Dar, poate fi asociat doar cu un părinte (nu ca cu o categorie).

 Doc 1
↳ Doc 2
↳ Doc 3
↳ Doc 4
↳ Documentul 5
↳ Doc 6

Există două beneficii pentru această structură:

E mai structurat. Te obligă să te gândești unde exact este locul cel mai potrivit pentru a adăuga articolul de documentare.
Categoriile nu au o „comandă” specifică. Prin urmare, nu există o modalitate ieșită din cutie de a organiza categoriile așa cum este posibil cu postările care au o proprietate menu_order .

Motivele de mai sus au fost exact motivul pentru care am decis să mergem cu pluginurile ierarhice.

Grozav – acum știu ce tip de structură de date avem nevoie pentru documentația noastră.

Apoi am petrecut timp citind despre două plugin-uri premium – wpDocs (versiunea pro a bazei de cunoștințe WP) și Heroic Knowledge Base. Ambele par impresionante din punct de vedere vizual, dar...

Nu am putut găsi nicio diferență semnificativă între cele două pluginuri premium și pluginurile gratuite.
Ambele plugin-uri folosesc structura de date plată, cu care am decis să nu mergem.

Deci da – probabil că au mai fost 10 plugin-uri la care nici măcar nu m-am uitat, dar modelul era clar.

Am decis să mergem cu weDocs peste WP Help din mai multe motive:

Interfața de utilizare prin glisare și plasare a setărilor de administrare a weDocs este modernă, ușor de utilizat și convingătoare din punct de vedere vizual.
WP Help nu vine cu taxonomie personalizată pentru documente. Ceea ce înseamnă că categoriile și etichetele nu sunt livrate din cutie.
WP Help nu acceptă deloc breadcrumbs.
weDocs a fost livrat cu un set de șabloane personalizate care vor face ca documentația să arate bine imediat (evident a necesitat o anumită personalizare a UI).
weDocs are un flux continuu de UI. La sfârșitul fiecărui articol, puteți naviga la următorul articol.

Să trecem la partea distractivă – implementarea...

Instalarea și personalizarea soluției de documentare weDocs

Pentru a începe, descărcați și instalați weDocs direct din depozitul WordPress.org:
https://wordpress.org/plugins/wedocs/

Acum este timpul să facem câteva personalizări:

Adăugarea metadatelor de fragmente îmbogățite de breadcrumbs

Deoarece nu am vrut să schimbăm plugin-ul propriu-zis (dacă este posibil), am folosit șablonul weDocs și funcțiile.php ale temei pentru a suprascrie randarea breadcrumbs implicită.

Copiați /wedocs/templates/single-docs.php în /your-theme/wedocs/single-docs.php .
Adăugați următorul cod în fișierul functions.php al temei:
Deschideți /your-theme/wedocs/single-docs.php și înlocuiți apelul la wedocs_breadcrumbs() cu freemius_wedocs_breadcrumbs() .
Deoarece am modificat, de asemenea, structura HTML a breadcrumb-urilor la o listă neordonată ( <ul> ) pentru o semantică mai bună, adăugați următorul cod SASS la tema dvs.:

Pentru a completa fragmentele îmbogățite, va trebui să adăugați următorul cod la eticheta <body> :

<body<?php if ('docs' === get_post_type()){     echo ' itemscope itemtype="http://schema.org/WebPage"'; } ?>>

Personalizarea structurii URL a bazei de cunoștințe (permalink-uri)

weDocs este livrat cu următoarea structură implicită de permalink:
your-site.com/wordpress-root/docs/

Am vrut să avem documentația noastră pe freemius.com/help/documentation/ care ar trebui să se claseze mai bine în SEO atunci când căutăm documentație. De asemenea, am dorit să păstrăm pagina „ajutor” pentru a adăuga un Centru de ajutor în viitor, astfel încât să putem folosi structuri URL precum /help/faq/ pentru o pagină de întrebări frecvente și /help/forum/ pentru un forum.

Am putea realiza asta cu ușurință modificând regulile de rescriere ale docs CPT în codul pluginului. Dar, deoarece dorim să evităm modificarea codului pluginului, am găsit o modalitate de a face acest lucru indirect în fișierul functions.php al temei:
În plus, am adăugat suport pentru extrase de articole (avem nevoie de asta pentru următoarea personalizare), autorul documentelor, câmpurile personalizate și atributele paginii. Important: weDocs este structurat implicit pentru baza de cunoștințe cu mai multe produse. Astfel, dacă doriți să aveți structura /help/documentation/ , asigurați-vă că documentul de nivel superior pe care îl creați în back office se numește Documentație (slug-ul trebuie să fie documentation ).

Adăugarea unei pagini de pornire drăguță la baza de cunoștințe weDocs

În mod implicit, weDocs este livrat cu un cod scurt care vă poate ajuta să creați o pagină de pornire care va arăta astfel:

Nu este rău, dar personal prefer aspectul generat de Help Scout Docs :

Oferă o scurtă descriere a fiecărei secțiuni și mi se pare mai atrăgător din punct de vedere vizual. Mai întâi, să creăm șabloanele PHP adăugând docs-header-main.php și docs-sections.php în folderul /your-theme/wedocs/ . Puteți găsi codul în următorul esen: https://gist.github.com/vovafeldman/adbf1c071a08b7565df11d709b2f1240 Dacă vă plonjați în codul fișierului docs-header-main.php , veți observa că și eu m-am strecurat în căutarea bogată metadate pentru fragmente. Acum, deoarece articolul /help/documentation/ este doar un alt articol din Baza de cunoștințe, șablonul implicit pe care îl va folosi WordPress este /wedocs/single-docs.php . Astfel, trebuie să adăugăm următorul fragment de cod în partea de sus a acelui fișier, pentru a încărca noile șabloane de secțiuni atunci când părintele articolului nu este setat:

if ( empty( $post->post_parent ) ) {
  wedocs_get_template_part( 'docs', 'header-main' );
  wedocs_get_template_part( 'docs', 'sections' );

  return;
}

Faceți weDocs Mobile friendly / receptiv

Din păcate, weDocs nu este livrat cu reguli CSS receptive. Iată cum arată în baza de cunoștințe weDevs (dezvoltatorii weDocs):

Nu mă voi scufunda în CSS, dar, în general, am adăugat interogări media care:

Ascunde pesmetul.
Faceți conținutul la lățime completă cu o căptușeală frumoasă.
S-au mutat bara laterală de navigare și căutarea în partea de jos, chiar înainte de subsol.

Iată rezultatul:

Și iată cum arată pagina secțiunilor:

Grozav! Am terminat cu personalizarea weDocs.

Folosind Markdown în loc de HTML Rich Editing

Una dintre cerințele inițiale ale KB a fost sustenabilitatea – abilitatea de a schimba cu ușurință designul și, eventual, o platformă (vă amintiți?). Utilizarea HTML Editarea conținutului bogat este o sabie cu două tăișuri. Pe de o parte, este extrem de flexibil și oferă libertatea de a personaliza stilul de conținut după cum doriți. Pe de altă parte, această lipsă de structură permite fiecărui scriitor de conținut să facă ceea ce vrea. Acest lucru nu este durabil, face schimbările de design complexe și migrarea și mai dificilă. De exemplu, folosind <strong> vs. <b> . Sau folosind tabele bazate pe <table> vs. <div> . Acestea sunt decizii legate de sintaxă și fiecare persoană are stilul său unic de scriere.

Pe ce ar trebui să se concentreze scriitorii de conținut este conținut și semantică, nu design.

Există o mulțime de limbaje de marcare cu sintaxă de formatare a textului simplu, deși Markdown a fost alegerea naturală, deoarece este utilizat pe scară largă de giganți precum GitHub, Atlassian și WordPress însuși.

Alegerea și instalarea unui plugin WordPress Markdown

Există doar două pluginuri Markdown în depozitul WordPress.org care au peste 1.000 de instalări active. WP-Markdown și JP Markdown. Da, Jetpack are și un modul Markdown, dar nu avea sens să instalezi acest „monstru” doar pentru un singur modul. Inițial, am instalat WP-Markdown deoarece, pe baza capturilor de ecran, avea opțiunea de a selecta cu ușurință ce tipuri de postări vor accepta markdown. Din păcate, pluginul nu a funcționat (ultima actualizare a fost acum peste 3 ani), așa că am ajuns să nu-l folosim. Apoi, am instalat JP Markdown. Plugin-ul a funcționat, dar a avut câteva lucruri care nu mi-au plăcut:

Reducerea a fost activată automat pe toate postările și paginile.
Sintaxa markdown nu a fost păstrată, a fost convertită automat în stil HTML:

Acest lucru este rău, deoarece datele sunt stocate în baza de date ca HTML bogat și nu ca markdown (am verificat asta). De asemenea, nu adaugă nicio restricție privind editarea HTML bogat. Deci, dacă în viitor dorim să migrăm către un alt sistem, nu există nicio modalitate de a exporta reducerea.

Apoi am găsit WP Markdown Editor care folosește modulul Markdown de la Jetpack și acesta a fost cel pe care am ajuns să-l folosim. Chiar dacă a trebuit totuși să facem câteva personalizări:

Pluginul dezactivează editarea bogată din toate postările și paginile la activare. Am vrut să scăpăm de editarea bogată doar pe paginile noastre de documentație.
Plugin-ul înlocuiește editorul existent cu propriul editor de reducere pentru toate postările și paginile. Din nou, am vrut să avem asta doar pe paginile noastre de documentație.

Puteți vedea aceste modificări aici:
https://github.com/Freemius/wp-markdown-editor/commit/706bce0c23943c82d102c67a09e18dac32c66207

Puteți descărca versiunea bifurcată de aici (doar câteva mici modificări):
https://github.com/Freemius/wp-markdown-editor

Apoi, am adăugat o funcție scurtă care înregistrează docs CPT pentru a accepta editarea reducerii și anulează înregistrarea tipurilor de post și page pentru a păstra editorul HTML bogat:

În cele din urmă, a trebuit să modificăm funcționalitatea implicită de export a WordPress, astfel încât să exporte codul de reducere și nu conținutul bogat în HTML. Am făcut-o prin conectarea la the_content_export :
Minunat – KB nostru este alimentat de markdown și poate fi exportat cu ușurință.

Adăugarea suportului pentru YouTube și Vimeo Markdown

Videoclipurile sunt o parte esențială a oricărei baze de cunoștințe. Din păcate, Markdown nu acceptă videoclipuri. Din fericire, WordPress face foarte ușor să adăugați cod scurt și cu câteva linii de cod. Ne-am îmbogățit sintaxa Markdown pentru a sprijini adăugarea videoclipurilor YouTube și Vimeo:

Ca bonus, am făcut ca dimensiunea videoclipului să fie receptivă și prietenoasă cu dispozitivele mobile, iar adăugarea videoclipurilor este acum intuitivă și simplă cu ID-ul video:
[youtube gj6aoYG4fUI]
[vimeo 185625717]

Adăugarea de asistență pentru coduri scurte pentru înștiințări frumoase

Sintaxa implicită Markdown acceptă ghilimele bloc, dar nu vine cu semantică pentru diferite înștiințări, cum ar fi sfaturi și avertismente, care nu sunt obligatorii, dar importante pentru o bună bază de cunoștințe.

Codurile scurte WordPress pentru salvare din nou

Și iată cum arată pe front-end:

Am adăugat prefixul fs_ pentru a preveni eventualele conflicte cu pluginurile pe care le-am putea instala în viitor.

Adăugarea SyntaxHighlighter pentru Pretty Code

Nici WordPress, nici WP Markdown Editor, nu vin cu evidențierea sintaxei codului. Deoarece Freemius este o platformă pentru dezvoltatori și documentația noastră vine cu exemple de cod, adăugarea evidențierii sintaxei a fost crucială. Am ales să mergem cu SyntaxHighlighter Evolved, deoarece este alimentat de Automattic, la fel ca modulul de bază Markdown al Jetpack care este utilizat de pluginul WP Markdown Editor. Privind codul de redare de reducere, arată că s-au integrat de fapt împreună:

$this->use_code_shortcode = class_exists( 'SyntaxHighlighter' );

Minunat! Dreapta? Din nefericire, se pare că nimic nu este perfect din cutie și codul a fost redat incorect. A încurcat secțiunile de cod cu mai multe linii Markdown prin evadarea caracterelor speciale în entitățile HTML corespunzătoare. Nu numai că „spărgea” codul randat pe front-end, ci și stoca o versiune HTML scapă a părților de cod ale Markdown în baza de date. Și asta este rău pentru păstrarea conținutului și pentru exportul potențial de date. Astfel, nu am avut de ales decât să facem câteva ajustări în codul pluginului. Puteți vedea modificările exacte aici:
https://github.com/Freemius/wp-markdown-editor/commit/672695be8b29c57f7fa7ca580d29368b9e57af68

Acum avem o bază de cunoștințe frumoasă, compatibilă cu dispozitivele mobile, bazată pe Markdown, cu suport video, înștiințări și evidențiere a sintaxei codului. Da!

Încă trebuie să o facem rapid și sigur (aproape acolo!).

Cum am făcut baza noastră de cunoștințe WordPress super rapidă?

Am ales WP Super Cache pentru că este foarte popular (peste 1 milion de instalări active), dezvoltat și întreținut de Automattic, gratuit și relativ ușor de configurat.

Adăugarea permisiunilor de disc

Creați un folder de stocare în cache care poate fi scris: mkdir /path/to/your/wordpress/wp-content/cache/ setfacl -Rm user:apache:rwx /path/to/your/wordpress/wp-content/cache Dacă linia de permisiuni nu a făcut-o de lucru, utilizați următoarele: chmod 777 /path/to/your/wordpress/wp-content/cache/

Activarea memoriei cache

Activați stocarea în cache adăugând următoarele în fișierul wp-config.php :

/** Enable Caching */
define('WP_CACHE', true);
define( 'WPCACHEHOME', '/path/to/your/wordpress/wp-content/plugins/wp-super-cache/' );

Acum tot ce ne trebuie este să activăm memorarea în cache, o puteți face prin WP Admin → Setări → WP Super Cache: Nu uitați să faceți clic pe butonul „Actualizare stare” pentru a salva. Puteți verifica dacă memorarea în cache funcționează deschizând orice pagină de pe site-ul dvs. WordPress în modul incognito și verificând codul sursă. Când WP Super Cache funcționează, ar trebui să vedeți următorul comentariu HTML în partea de jos a codului sursă al paginii:

<!-- Dynamic page generated in 0.848 seconds. -->
<!-- Cached page generated by WP-Super-Cache on 2016-10-13 21:35:40 -->

<!-- super cache -->

Este deja mult mai bine decât a servi paginile fără cache. Dar, acest lucru încă declanșează întregul teanc de PHP, WordPress și MySql. Dacă vrem să facem site-ul nostru rapid, trebuie să adăugăm cache la nivel de server.

Configurarea memoriei cache la nivel de server

Dacă utilizați Nginx, așa cum suntem noi, iată configurația pe care am folosit-o: WP Super Cache Reguli de configurare Nginx SFAT: Regulile de configurare Nginx includ o mulțime de reguli if . Pentru a vă economisi timp prețios, asigurați-vă că toate if regulile sunt în afara directivei privind location , în caz contrar, se va întrerupe întreaga procesare (am pierdut câteva ore să-mi dau seama). Dacă utilizați Apache, puteți găsi regulile .htaccess mod_rewrite chiar în pagina cu instrucțiuni de instalare a pluginului de pe WordPress.org: https://wordpress.org/plugins/wp-super-cache/installation/ Cel mai simplu mod de a testa Memorarea în cache la nivel de server fără a vă afecta site-ul se face urmând acești pași:

Creați și publicați o postare inactivă, setați următorul slug `dummy-cache-test`.
Încărcați pagina în modul browser incognito, asigurându-vă că este stocată în cache.

Adăugați următorul cod în partea de sus a fișierului wp-config.php :

if ( false !== strpos($_SERVER[REQUEST_URI], 'dummy-cache-test') {
    echo 'Server caching is off';
    exit;
}

După ce adăugați codul, reîncărcați pagina în același mod de browser incognito. Dacă pagina este încărcată corect – stocarea în cache la nivel de server este ON Dacă primiți mesajul „Server caching este dezactivat”, atunci ceva nu este în regulă.

Nu uitați să eliminați acea adăugare din fișierul wp-config.php și, de asemenea, să ștergeți postarea falsă când ați terminat. Fantastic – am setat memorarea în cache, toate paginile sunt acum servite direct din fișierele HTML statice stocate în cache, omitând PHP și WordPress.

Adăugarea CDN-ului

Chiar dacă KB este deja într-o formă destul de bună, fiecare vizualizare de pagină dintr-un browser nou va „lovi” serverul nostru. Astfel, vreau să elimin asta adăugând încă un strat – CDN.

Beneficiile clare ale CDN sunt distribuția globală a centrelor de date, disponibilitatea ridicată și o scădere masivă a resurselor serverului, mai ales atunci când lucrurile sunt statice. Paginile vor fi încărcate direct de pe CDN-ul fără să „atingă” serverele noastre.

Nu pot vorbi destul de bine despre CloudFlare. Le folosim CDN-ul (și bunătățile suplimentare) de ani de zile și ce este nebunesc în toate acestea - îl puteți folosi gratuit! Este corect – absolut gratuit pentru 95% din funcțiile lor.

Doar pentru a vă da un exemplu, să presupunem că aveți o pagină statică populară pe site care primește 5 milioane de vizite unice zilnic. Ignorând serverele proxy și memorarea în cache ISP, acest lucru ar declanșa cel puțin 5 milioane de accesări zilnice la serverul dvs. Când utilizați un CDN precum CloudFlare, această pagină statică va fi încărcată de pe site-ul dvs. doar de câteva ori pe zi (pe baza frecvenței de curățare a memoriei cache CDN).

Iată câteva statistici reale dintr-un subdomeniu pe care îl avem și care servește doar imagini:

Uită-te la acele cifre – am economisit peste 600 GB de lățime de bandă pentru serverele noastre. Dacă ați configurat WordPress + WP Super Cache Plugin + Server Level Caching + CloudFlare CDN, probabil că puteți utiliza o picătură DigitalOcean de 5 USD / lună fără probleme de scalare!

Să facem niște calcule împreună... WordPress este gratuit, WP Super Cache este gratuit, CloudFlare CDN este gratuit... Oh, este doar 5 USD/lună pentru WordPress scalabil. Nebun, nu?!

Cum am personalizat căutarea KB pentru a servi date din cache?

În mod implicit, structura permalink-urilor de căutare WordPress folosește un parametru șir de interogare s= pentru a trece interogarea de căutare. Dintr-un motiv întemeiat, WP Super Cache ignoră șirurile de interogare. Prin urmare, a trebuit să facem câteva mici ajustări în structura URL-urilor de căutare pentru ca aceasta să funcționeze:

Această actualizare modifică structura URL-ului în freemius.com/help/documentation/search/{query}/ care este stocată în cache de WP Super Cache.

Bum! Chiar și rezultatele căutării noastre sunt stocate în cache acum.

Cum ne-am asigurat baza de cunoștințe WordPress?

Securitatea este o cheie. Ultimul lucru cu care dorește să se ocupe orice companie, în special un startup, este o breșă de securitate. Vă poate afecta reputația, vă poate risca IP (proprietatea intelectuală) și vă poate lua ore, uneori chiar zile, pentru a recupera controlul și datele.

Mulți dezvoltatori le place să vorbească prostii despre WordPress și spun că este nesigur. Pe baza cifrelor – da, probabil că au dreptate. Întrucât WordPress este cea mai populară platformă web, este, de asemenea, ținta numărul 1 pentru hackeri, iar cifrele au sens - Duh...

Ceea ce nu înțeleg este că WordPress ca platformă este probabil unul dintre cele mai sigure proiecte. The vulnerabilities are mainly coming from old, outdated WordPress versions, 3rd party plugins and themes, and from users that set up weak passwords.

So the first thing we would like to do is eliminate any notion of WordPress in our source code to reduce the chances of an attack.

1. WordPress adds a bunch of (mostly) unuseful metadata to the head of every page which is pretty much unique to WordPress, let's get rid of that by adding the following code to the theme's functions.php file:

2. Many WordPress plugins add HTML comments with a unique thumbprint that are easily identified. For example, Yoast SEO adds the following code:

<!-- This site is optimized with the Yoast SEO plugin v3.7.0 - https://yoast.com/wordpress/plugins/seo/ -->

That makes it easy for attackers to identify the site as WordPress.

Remember CloudFlare?

It has a checkbox to automatically minify HTML and get rid of all the HTML comments added by different plugins, themes and WordPress core:

Terminat!

3. Another known identifier of WordPress is the /wp-admin/ path to the login page. We installed WPS Hide Login, and configured our own “secret” path to the login page.

Assuming you set your login to your-site.com/my-secret-login/ make sure you add that path to WP Super Cache exclusion list. You can find it under WP Admin → Settings → WP Super Cache → Advanced:

Otherwise, it might mess up things when using SSL.

4. No need to mention – you and your team should be keeping your passwords strong! You can use a plugin like Force Strong Password to enforce a 'strong passwords' policy.

5. Force your login and WP Admin browsing via HTTPS to prevent password sniffing. You can achieve that by adding the following defines to the wp-config.php file:

define('FORCE_SSL_ADMIN', true);
define('FORCE_SSL_LOGIN', true);

6. One of the most popular attacks on WordPress sites is Brute force attack. Having a strong password policy helps, but can't really protect against it. Thus, we installed Google Captcha plugin that adds a simple captcha validating it's a human being:

Also, we installed Login Watchdog, a lightweight plugin that automatically bans suspicious IPs after pre configured amount of failed logins.

And if you are using CloudFlare as I recommended, it comes with a security layer against any threats, and since it's widely used, it has a “network knowledge” to protect your site from IPs that were attacking other sites powered by CloudFlare.

7. You should also secure WordPress on the server layer, preventing direct access to files like wp-login.php , hiding sensitive files, etc. Just follow this post:
https://lamosty.com/2015/04/14/securing-your-wordpress-site-running-on-nginx/

So yes – as long as there is a login page to our WordPress, it would never be secure as a pure static website. But the fact that we have turned our KB's frontend to static, hidden any evidence that we are using WordPress, added brute force protection and forced the login via HTTPS with a strong password policy, makes it very very (very) hard to hack.

I would dare to say that the only way the Knowledge Base will be hacked is if a security dojo will target our site specifically (that's rare, and I'm NOT calling anyone for a challenge).

Now you

Hopefully, this (very) elaborate article/tutorial will be useful for you when you come to make the important decision of what to go with for your knowledge base documentation solution.
No doubt, there's a lot to take into account here, and many of the decisions we made were influenced by our very specific needs & desires.

You could either copy & paste the entire process and customizations, or go deeper and customize it according to your specific needs. What's more important is to grasp the line of thought that lead the decision making and choosing & picking what's right for us. It was not easy because as I've shown – there are quite a few viable options out there, however, it did pay off, as Freemius now has an awesome Knowledge Base center, which is super customizable, lightning fast and scalable!

Hope you have a clear view how you can get started implementing and setting up your own documentation solution.

Noroc!