Share
Dus je hebt een geweldig thema, sjabloon of webapplicatie gemaakt. Nu voor het vervelende gedeelte; de documentatie. Het schrijven van de inhoud hoeft niet zo problematisch te zijn, het is waarschijnlijker dat er helpbestanden worden gemaakt die kostbare tijd kosten. Markdown, een lichtgewicht en * echt * eenvoudige opmaak-syntaxis kan dat allemaal voor u oplossen.
Markdown is gemaakt door John Gruber en is een syntaxis voor het maken van platte tekst, waardoor het maken van eenvoudige HTML-elementen een stuk eenvoudiger wordt.
In plaats van HTML-tags te gebruiken (die relatief gezien veel tijd kosten om te schrijven) is het de taak van Markdown om uit de weg te gaan van je denkproces, zodat je je op inhoud kunt concentreren. Omdat de syntaxis zo eenvoudig is, is het voor beide gemakkelijk schrijven en lezen Markdown. Later in deze zelfstudie doorlopen we de stappen voor het maken van themadocumentatie met Markdown, dus je zult zien hoe licht en snel het is!
Zodra je Markdown hebt leren schrijven, heb je een soort parseertoepassing nodig om je Markdown in HTML-markup te converteren.
De oorspronkelijke Markdown-converter is gemaakt in Perl, maar sindsdien zijn veel applicaties (op meerdere platforms) uitgekomen. Laten we eens naar enkele opties kijken, zowel online als op uw eigen systeem.
Dingus is een webapplicatie gemaakt door dezelfde mensen die je Markdown hebben gebracht. Kopieer en plak eenvoudig uw markdown-code in een teksteditor (of voer deze in het tekstgedeelte in) en met een klik op een knop verschijnt uw HTML-code (evenals een voorbeeld). Niets bijzonders, maar een eenvoudige manier om Markdown in HTML te converteren.
MarkdownPad is een geweldige Windows-applicatie waarmee je eenvoudig Markdown-bestanden kunt maken (en het is gratis!) Het bevat geweldige functies zoals direct HTML-preview, eenvoudig formatteren met sneltoetsen, CSS-aanpassingen, HTML-export en zelfs een "afleidingsvrije" modus.
Mou is een geweldige, gratis Mac-applicatie waarmee je Markdown op een eenvoudige en mooie manier kunt schrijven. Het heeft geweldige functies, zoals aangepaste styling, sneltoetsen, live HTML, HTML export (met optionele CSS-stijl), PDF-export, dicteerondersteuning en meer. Voor deze zelfstudie gebruiken we Mou om de documentatie van ons thema te maken.
MarkdownNote is nog een geweldige applicatie om Markdown te schrijven en de iOS-applicatie is perfect als je Markdown onderweg wilt schrijven. Net als de andere applicaties die we hebben behandeld, heeft het enkele geweldige functies, waaronder live HTML-voorbeeld, sneltoetsen op het toetsenbord en synchronisatie met Dropbox.
Tot nu toe hebben we besproken wat Markdown is en hebben we een aantal tools opgezocht die je kunt gebruiken om Markdown te schrijven. Laten we nu een aantal themadocumentatie maken voor een niet-bestaand thema, over wat u normaal gesproken zou moeten opnemen in documentatie, de Markdown-syntaxis en praktische tips.
Tijdens de volgende stappen zullen we kijken naar Markdown als het van toepassing is op onze behoeften. Voor een meer diepgaande blik op de Markdown-syntaxis, bekijk Markdown: de ins en outs op Nettuts+.
Omdat u ken de in's en out's van uw thema / sjabloon / webapp al, het lijkt misschien een beetje vervelend om de basis te behandelen. Het doel van een documentatiebestand is om als gids voor andere gebruikers en kopers te dienen. Vaak is er een installatie, aanpassing en een paar aanpassingen nodig waar gebruikers over moeten weten - en het is jouw taak om ze op te leiden. Dit is wat we zouden willen opnemen:
Vergeet niet dat documentatie eenvoudig genoeg moet zijn voor iedereen met basiskennis om te begrijpen, maar ook om te bespreken hoe belangrijke bestanden kunnen worden gewijzigd. U hoeft bijvoorbeeld niet per se te laten zien hoe u specifieke CSS-waarden kunt wijzigen, maar u moet wel laten zien hoe u deze bestanden kunt openen.
Nu is het tijd voor de leuke dingen! Ga je gang en open je Markdown-editor (ik gebruik Mou voor Mac). Maak een header voor uw documentatiebestand:
#Thema-documentatie
Koerselementen kunnen eenvoudig worden geschreven door een tot zes # 's vóór de inhoud toe te voegen. In het bovenstaande voorbeeld hebben we één # -teken gebruikt om een te maken h1 element met de tekst 'Themadocumentatie'. Als u een wilt maken h3 element, zou je schrijven ### Kop 3.
Laten we nu een horizontale regel maken (
***
Een belangrijk onderdeel om toe te voegen aan uw documentatie is een informatiegedeelte.
* Naam van het thema: * Thema * Auteur: * Suhail Dawood * Gemaakt: * 08/08/2012 * Versie: * 1.0.1 *** Bedankt voor uw aankoop! Als je vragen hebt over dit thema, stuur me dan een e-mail naar **[email protected]** of tweet me ** @ tutsplus ** ***
Laten we het HTML-equivalent van de bovenstaande Markdown-code eens bekijken:
Naam van het thema: Thema
Schrijver: Suhail Dawood
gemaakt: 08/08/2012
Versie: 1.0.1
dank voor uw aankoop! Als je vragen hebt over dit thema, aarzel dan niet om me een e-mail te sturen naar [email protected] of tweet me @tutsplus
Alleen al door naar de twee verschillende bronnen te kijken, kun je meteen zien dat Markdown veel intuïtiever is om te begrijpen en te creëren. In plaats van constant toe te voegen <en >Met Markdown kunt u zich concentreren op de inhoud. Voeg om te benadrukken een asterisk toe voor en na de tekst (bijv. * Benadrukte tekst *). Om toe te moedigen, voeg je toe twee sterretjes voor en na de tekst (bijv. ** Aangemoedigde tekst **). Als u een regeleinde wilt toevoegen, voegt u eenvoudig twee spaties toe op het punt waar u een regeleinde wilt invoegen.
Laten we nu een inhoudsopgave toevoegen aan ons Markdown-bestand:
## Inhoudsopgave 1. HTML-structuur 2. CSS-bestanden 3. Javascript-bestanden 4. PSD-bestanden 5. Themastijlen 6. JavaScript aanpassen 7. CSS twerken 8. Browsercompatibiliteit ***
Als we dit in HTML zouden maken, zou je het volgende willen zien:
Inhoudsopgave
- HTML-structuur
- CSS-bestanden
- Javascript-bestanden
- PSD-bestanden
- Thema-stijlen
- JavaScript aanpassen
- CSS aanpassen
- Browsercompatibiliteit
In plaats van een geordende lijst en afzonderlijke lijstitems te moeten maken, schrijft u gewoon 1. Eerste element en blijf geïncrementeerde items toevoegen.
Het is belangrijk om uw gebruikers te laten weten hoe de bestanden van de site zijn ingedeeld. Omdat we documentatie voor een thema maken, moeten we aangeven hoe de HTML-code van het thema is gestructureerd. We kunnen dit met de volgende code schetsen:
## 1. HTML-structuur De HTML-structuur voor elke pagina is als volgt: * Meta * Link naar CSS-bestanden * Header * Logo * Sociale links * Navigatie * Hoofdinhoud * Inhoudschuifregelaar * Artikelen * Zijbalk * Zoeken * Archieven plaatsen * Mailinglijst * Link naar Javascript Bestanden * Javascript ***
Eenvoudig. Om onze inhoudsopgave te maken, hebben we een geordende lijst gebruikt. In deze sectie hebben we gebruikt genesteld ongeordende lijsten. Als u een ongeordende lijst wilt maken in Markdown, voegt u eenvoudig een asterisk en een spatie toe vóór de tekst (bijv. * Item 1). Om lijstitems te nesten, spring gewoon naar binnen en maak een ander lijstitem.
Vooral in thema's is CSS-documentatie erg belangrijk. Het is een goed idee om de verschillende CSS-bestanden die in het thema zijn opgenomen, te beschrijven, evenals een korte beschrijving van elk bestand:
## 2. CSS-bestanden Er zijn 3 CSS-bestanden in dit thema: * main.css * colors.css * skeleton.css ##### main.css Dit CSS-bestand is het belangrijkste stylesheet voor het thema. Het bevat alle waarden voor de verschillende elementen van het thema en het standaardkleurenschema. ##### colors.css Dit CSS-bestand bevat de vormgeving van alle andere kleurenschema's die in het thema zijn opgenomen. ##### skeleton.css Dit CSS-bestand zorgt ervoor dat het thema responsief is, en past zich aan aan verschillende schermformaten. ***
Zorg ervoor dat u kopjes gebruikt om verschillende secties van het documentatiebestand te scheiden. Een mooi ingedeeld documentatiebestand zal leiden tot minder verwarde gebruikers!
Als uw thema Javascript-bestanden bevat, is het een goed idee om ze op zijn minst in de documentatie te vermelden:
## 3. Javascript-bestanden Er zijn 2 Javascript-bestanden in dit thema: * jquery.js * slider.js ##### jquery.js Dit thema maakt gebruik van de JavaScript-bibliotheek jQuery. ##### slider.js De inhoudschuifregelaar in het thema draait op dit Javascript-bestand. Er zijn enkele instellingen die kunnen worden aangepast, dit wordt behandeld in het gedeelte 'JavaScript aanpassen'. ***
Zorg ervoor dat u niet alleen een lijst opslaat, maar ook de bestanden in uw thema beschrijft. Hierdoor wordt het voor de gebruiker een stuk eenvoudiger om de inhoud van elk bestand te begrijpen en te beslissen of ze er al dan niet mee willen rotzooien.
Hoewel er een aparte sectie is voor PSD-sjablonen op ThemeForest, hebben veel auteurs besloten om PSD-bestanden met hun gecodeerde sjablonen op te nemen, zodat de gebruiker de vrijheid heeft om ontwerpwijzigingen aan te brengen. Als je thema PSD-bestanden bevat, is het misschien een goed idee om ze te schetsen, net zoals we dat met alle andere bestanden hebben gedaan:
## 4. PSD-bestanden In dit thema zijn 5 verschillende PSD-bestanden opgenomen: 1. startpagina.psd 2. about.psd 3. portfolio.psd 4. blog.psd 5. contact.psd Deze PSD-bestanden zijn handig als u deze wilt maken veranderingen in het ontwerp van het thema. U kunt ook een nieuwe pagina-indeling maken met behulp van de bestaande PSD-bestanden als basis om mee te werken. ***
Het is het beste om uw PSD-bestanden een duidelijke naam te geven (bijvoorbeeld volledige breedte-pagina.psd) in plaats van vage namen (bijvoorbeeld template-003.psd). Op deze manier kunnen gebruikers vinden wat ze nodig hebben zonder elk bestand te hoeven openen.
Hoogstwaarschijnlijk bevat uw thema een selectie kleurenschema's waaruit uw gebruikers kunnen kiezen. Als dit het geval is, zorg dan dat u aangeeft hoe dit wordt gedaan:
## 5. Thema-stijlen Bij dit thema zijn er 10 verschillende themastijlen: 1. Licht 2. Donker 3. Grijs 4. Groen 5. Rood 6. Oranje 7. Blauw 8. Paars 9. Bruin 10. Donkerblauw Ga naar om deze stijlen te wijzigen. de WordPress-backend, selecteer ** Opties> Stijlen ** en selecteer de gewenste stijl. ***
In het bovenstaande voorbeeld heb ik de verschillende kleurenschema's die deel uitmaken van het thema opgesomd en getoond hoe u ze kunt wijzigen.
Als uw code Javascript-bestanden bevat die aanpassingsparameters hebben (bijvoorbeeld een schuifregelaar), is het een goed idee om uw gebruikers te laten zien hoe ze deze waarden kunnen manipuleren:
## 6. JavaScript aanpassen De inhoudschuifregelaar in het thema loopt van slider.js af en er zijn een aantal waarden die kunnen worden gewijzigd om het uiterlijk en het gevoel van de schuifregelaar te wijzigen. ##### Waarden wijzigen In slider.js kunt u deze waarden wijzigen:auto: true* Boolean: automatisch animeren, waar of onwaar *snelheid: 1000* Geheel getal: snelheid van de overgang, in milliseconden *pager: waar* Boolean: Toon pager, waar of onwaar *nav: false* Boolean: navigatie tonen, true of false * ***
De bovenstaande code geeft aan hoe een gebruiker waarden kan wijzigen. Om de code te stijlen, wikkel je de relevante tekst erin -tags. Toepassingen zoals Mou voegen styling toe aan deze elementen in de live preview en je kunt de code ook exporteren om de styling te behouden. We zullen het een beetje hebben over het later exporteren van uw documentatie.
CSS-bestanden worden vaak door een gebruiker aangepast. Ze zullen het zeker als nuttig beschouwen als u een sectie toevoegt aan de documentatie die laat zien hoe u de CSS-bestanden kunt openen, zodat ze deze kunnen bewerken.
## 7. CSS tweaken Het thema is gebaseerd op een responsief framework, waardoor inhoud op alle schermformaten optimaal te zien is. ##### De CSS veranderen Start door naar de WordPress-backend te gaan, ** Thema's> Thema> Bron bekijken **. Selecteer het * style.css * -bestand om te bekijken en de mogelijkheid om de code te bewerken. Hier kunt u dingen veranderen zoals lettertypen, grootten, kleuren, enz. ***
Nu de gebruiker toegang heeft tot het CSS-bestand, kunnen ze de gewenste wijzigingen aanbrengen.
Het is een goed idee om de gebruiker op de hoogte te stellen van problemen met browsercompatibiliteit:
## 8. Browsercompatibiliteit Dit thema werkt goed (-) of goed (X) in de volgende browsers: ** IE 6-8 ** - ** IE 9 + ** X ** Chrome ** X ** Firefox ** X ** Safari ** X ** Opera ** X ***
Als u dit gedeelte wilt uitbreiden, kunt u in bepaalde browsers aangeven welke functies van het thema eronder lijden.
Ter aanvulling van onze documentatie voegen we een sectie toe om onze gebruikers te laten weten hoe ze contact met ons kunnen opnemen als ze nog vragen hebben. Laten we dit stukje code toevoegen:
Accentsconagua
