Share
Quindi hai creato un fantastico tema, modello o applicazione web. Ora per la parte noiosa; la documentazione. Scrivere il contenuto non sarà necessariamente così problematico, è più probabile che crei i file di aiuto che impiegheranno del tempo prezioso. Markdown, una sintassi di formattazione leggera e * veramente * semplice può risolvere tutto ciò che per te.
Creato da John Gruber, Markdown è una sintassi di formattazione del testo semplice che rende molto più semplice la creazione di elementi HTML di base.
Invece di usare i tag HTML (che, relativamente parlando, impiegano molto tempo per scrivere), il lavoro di Markdown è quello di togliersi di mezzo il processo di pensiero, permettendoti di concentrarti sui contenuti. Perché la sintassi è così semplice, è facile per entrambi Scrivi e leggere Markdown. Più avanti in questo tutorial, illustreremo i passaggi della creazione della documentazione del tema utilizzando Markdown, quindi vedrai quanto è leggero e veloce!
Una volta che hai imparato a scrivere Markdown, avrai bisogno di un qualche tipo di applicazione di analisi per convertire il Markdown in markup HTML.
Il convertitore Markdown originale è stato creato in Perl, ma da allora sono apparse molte applicazioni (su più piattaforme). Diamo un'occhiata ad alcune opzioni, sia online che eseguite sul tuo sistema.
Dingus è un'applicazione web creata dalle stesse persone che ti hanno portato Markdown. Basta copiare e incollare il codice Markdown da un editor di testo (o inserirlo nell'area di testo) e con un clic di un pulsante, verrà visualizzato il codice HTML (così come un'anteprima). Niente di eccezionale, ma un modo semplice per convertire Markdown in HTML.
MarkdownPad è una fantastica applicazione per Windows che ti permette di creare facilmente i file Markdown (ed è gratis!) Include fantastiche funzionalità come l'anteprima istantanea dell'HTML, una facile formattazione con scorciatoie da tastiera, personalizzazione CSS, esportazione HTML e persino una modalità "distraction free".
Mou è un'ottima applicazione Mac gratuita che ti consente di scrivere Markdown in modo semplice e bello. Ha grandi funzionalità come stile personalizzato, scorciatoie da tastiera, HTML live, esportazione HTML (con lo stile CSS opzionale), esportazione PDF, supporto per dettatura e altro. Per questo tutorial, useremo Mou per creare la documentazione del nostro tema.
MarkdownNote è un'altra fantastica applicazione per scrivere Markdown e l'applicazione iOS è perfetta se vuoi scrivere Markdown in movimento. Proprio come le altre applicazioni che abbiamo trattato, ha alcune funzioni eccezionali, tra cui l'anteprima HTML in tempo reale, le scorciatoie da tastiera e la sincronizzazione di Dropbox.
Finora, abbiamo coperto ciò che Markdown è e ho cercato alcuni strumenti che è possibile utilizzare per scrivere Markdown. Ora creiamo una documentazione a tema per un tema inesistente, che includa in genere ciò che dovresti includere nella documentazione, la sintassi Markdown e le migliori pratiche.
Durante i seguenti passaggi guarderemo Markdown come si applica alle nostre esigenze. Per uno sguardo più approfondito alla sintassi Markdown, controlla Markdown: The Ins and Outs over su Nettuts+.
Perché tu conosci già gli ingressi e i ritardi del tuo tema / modello / applicazione web, potrebbe sembrare un po 'noioso coprire le nozioni di base. Lo scopo di un file di documentazione è di servire da guida per altri utenti e acquirenti. Spesso, c'è l'installazione, la personalizzazione e alcuni ritocchi che gli utenti dovranno conoscere - e il tuo compito è educarli. Questo è ciò che potremmo voler includere:
Ricorda, la documentazione dovrebbe essere abbastanza semplice da consentire a chiunque abbia una conoscenza di base di comprendere, ma anche di capire come modificare i file importanti. Ad esempio, non devi necessariamente mostrare come modificare specifici valori CSS, ma devi mostrare come accedere a questi file.
Ora è il momento per le cose divertenti! Vai avanti e apri il tuo editor Markdown (userò Mou per Mac). Crea un'intestazione per il tuo file di documentazione:
#Theme Documentation
Gli elementi di intestazione possono essere scritti semplicemente aggiungendo da uno a sei # di fronte al contenuto. Nell'esempio sopra, abbiamo usato un segno # per creare un h1 elemento con il testo "Documentazione tematica". Se vuoi creare un h3 elemento, dovresti scrivere ### Intestazione 3.
Ora, creiamo una regola orizzontale (
***
Una sezione importante da aggiungere alla tua documentazione è una sezione informativa.
* Nome del tema: * Tema * Autore: * Suhail Dawood * Data di creazione: * 08/08/2012 * Versione: * 1.0.1 *** Grazie per l'acquisto! Se avete domande su questo tema, sentitevi liberi di mandarmi un'e-mail a **[email protected]** o twittarmi ** @ tutsplus ** ***
Diamo un'occhiata all'equivalente HTML del codice Markdown sopra:
Nome del tema: Tema
Autore: Suhail Dawood
Creato: 08/08/2012
Versione: 1.0.1
Grazie per il vostro acquisto! Se avete domande su questo tema, sentitevi liberi di inviarmi un'e-mail a [email protected] o twittami @tutsplus
Solo guardando le due diverse fonti, puoi immediatamente vedere che Markdown è molto più intuitivo da comprendere e creare. Invece di dover costantemente aggiungere <e >'s, Markdown ti permette di concentrarti sul contenuto. Per sottolineare, aggiungi un asterisco prima e dopo il testo (ad es. * Testo enfatizzato *). Per incoraggiarlo, aggiungi Due asterischi prima e dopo il testo (ad es. ** Testo rafforzato **). Per aggiungere un'interruzione di riga, aggiungi semplicemente due spazi nel punto in cui desideri inserire un'interruzione di riga.
Ora aggiungiamo un elenco di contenuti nel nostro file Markdown:
## Sommario 1. Struttura HTML 2. File CSS 3. File Javascript 4. File PSD 5. Stili dei temi 6. Tweaking Javascript 7. Ottimizzazione CSS 8. Compatibilità browser ***
Se dovessimo creare questo in HTML, ecco come apparirebbe:
Sommario
- Struttura HTML
- File CSS
- File Javascript
- File PSD
- Stili di tema
- Tweaking Javascript
- Modifica dei CSS
- Compatibilità del browser
Invece di dover creare un elenco ordinato e voci di elenco separate, è sufficiente scrivere 1. Primo elemento e continua ad aggiungere elementi incrementati.
È importante consentire agli utenti di definire i file del sito. Dato che stiamo creando documentazione per un tema, dovremmo delineare come è strutturato il codice HTML del tema. Possiamo delineare questo con il seguente codice:
## 1. Struttura HTML La struttura HTML per ogni pagina è la seguente: * Meta * Link ai file CSS * Intestazione * Logo * Link sociali * Navigazione * Contenuto principale * Cursore contenuto * Articoli * Barra laterale * Ricerca * Archivio post * Mailing List * Link to Javascript File * Javascript ***
Semplice. Per creare il nostro sommario, abbiamo usato una lista ordinata. In questa sezione, abbiamo usato nidificato liste non ordinate. Per creare un elenco non ordinato in Markdown, aggiungi semplicemente un asterisco e uno spazio prima del testo (ad es. * Articolo 1). Per nidificare gli elementi dell'elenco, basta rientrare verso l'interno e creare un altro elemento dell'elenco.
In particolare nei temi, la documentazione CSS è molto importante. È una buona idea delineare i diversi file CSS inclusi nel tema, nonché una breve descrizione di ciascun file:
## 2. File CSS Ci sono 3 file CSS in questo tema: * main.css * colors.css * skeleton.css ##### main.css Questo file CSS è il foglio di stile principale per il tema. Contiene tutti i valori per i diversi elementi del tema e lo schema di colori predefinito. ##### colors.css Questo file CSS contiene lo stile di tutti gli altri schemi di colori inclusi nel tema. ##### skeleton.css Questo file CSS consente al tema di essere reattivo, adattandosi a diverse dimensioni dello schermo. ***
Assicurati di utilizzare le intestazioni per separare diverse sezioni del file di documentazione. Un file di documentazione ben strutturato porterà ad un minor numero di utenti confusi!
Se il tuo tema include i file Javascript, è una buona idea almeno delinearli nella documentazione:
## 3. File Javascript Ci sono 2 file Javascript in questo tema: * jquery.js * slider.js ##### jquery.js Questo tema usa la libreria Javascript jQuery. ##### slider.js Il dispositivo di scorrimento del contenuto nel tema viene eseguito su questo file Javascript. Ci sono alcune impostazioni che possono essere ottimizzate, che saranno trattate nella sezione "Tweaking Javascript". ***
Assicurati di non solo elencare, ma descrivere i file nel tuo tema. Questo renderà molto più facile per l'utente comprendere il contenuto di ciascun file e decidere se vogliono o meno scherzare con esso.
Anche se esiste una sezione separata per i modelli PSD su ThemeForest, molti autori hanno deciso di includere i file PSD con i loro modelli codificati per consentire all'utente la libertà di apportare modifiche al design. Se il tuo tema include file PSD, potrebbe essere una buona idea delinearli come abbiamo fatto con tutti gli altri file:
## 4. File PSD In questo tema sono inclusi 5 diversi file PSD: 1. homepage.psd 2. about.psd 3. portfolio.psd 4. blog.psd 5. contact.psd Questi file PSD ti saranno utili se desideri creare modifiche al design del tema. Puoi anche creare un nuovo layout di pagina usando i file PSD esistenti come base su cui lavorare. ***
È consigliabile denominare chiaramente i file PSD (ad esempio full-width-page.psd) anziché nomi vaghi (ad esempio template-003.psd). In questo modo, gli utenti possono trovare ciò di cui hanno bisogno senza dover aprire ogni file.
Molto probabilmente, il tuo tema includerà una selezione di combinazioni di colori tra cui i tuoi utenti potranno scegliere. Se questo è il caso, assicurati di delineare come è fatto:
## 5. Stili dei temi Incluse con questo tema sono 10 diversi stili di tema: 1. Luce 2. Scuro 3. Grigio 4. Verde 5. Rosso 6. Arancione 7. Blu 8. Viola 9. Marrone 10. Blu scuro Per cambiare questi stili, andare a il backend di WordPress, seleziona ** Opzioni> Stili ** e seleziona lo stile che desideri. ***
Nell'esempio sopra, ho elencato le diverse combinazioni di colori incluse nel tema e ho mostrato come modificarle.
Se il tuo codice include file Javascript che hanno parametri di personalizzazione (ad esempio uno script di scorrimento), sarebbe una buona idea mostrare ai tuoi utenti come manipolare questi valori:
## 6. Ottimizzazione del Javascript Il cursore del contenuto nel tema scappa da slider.js e ci sono un paio di valori che possono essere modificati per modificare l'aspetto del cursore. ##### Modifica dei valori In slider.js, puoi modificare questi valori:auto: vero* Booleano: animato automaticamente, vero o falso *velocità: 1000* Intero: velocità della transizione, in millisecondi *cercapersone: vero* Booleano: mostra il cercapersone, vero o falso *nav: false* Boolean: mostra la navigazione, vero o falso * ***
Il codice sopra illustra come un utente può modificare i valori. Per applicare uno stile al codice, racchiudi il testo pertinente all'interno tag. Applicazioni come Mou aggiungono stile a questi elementi nell'anteprima dal vivo e puoi anche esportare il codice per mantenere lo stile. Parleremo un po 'di come esportare la documentazione in seguito.
I file CSS sono spesso personalizzati da un utente. Lo considereranno certamente utile se aggiungi una sezione alla documentazione che mostra come accedere ai file CSS in modo che possano modificarli.
## 7. Tweaking CSS Il tema è basato su un framework reattivo, che consente di vedere il contenuto in modo ottimale su tutte le dimensioni dello schermo. ##### Cambiare il CSS Inizia andando nel backend di WordPress, ** Temi> Temi> Visualizza sorgente **. Seleziona il file * style.css * per visualizzare e avere la possibilità di modificare il codice. Qui puoi cambiare cose come caratteri, dimensioni, colori, ecc. ***
Ora che l'utente ha accesso al file CSS, può apportare le modifiche che desidera.
È una buona idea informare l'utente di eventuali problemi di compatibilità del browser:
## 8. Compatibilità con il browser Questo tema funziona bene (-) o ottimo (X) nei seguenti browser: ** IE 6-8 ** - ** IE 9 + ** X ** Chrome ** X ** Firefox ** X ** Safari ** X ** Opera ** X ***
Se desideri espandere questa sezione, potresti spiegare quali caratteristiche del tema risentono in alcuni browser.
Per completare la nostra documentazione, aggiungeremo una sezione per consentire ai nostri utenti di sapere come contattarci se hanno ulteriori domande. Aggiungiamo questo bit di codice:
Accentsconagua
