A new Riff-radio.org site with a static approach.

manual.html 242KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774
  1. <dl class="docinfo simple">
  2. <dt class="version">Version<span class="colon">:</span></dt>
  3. <dd class="version">8.2.3</dd>
  4. </dl>
  5. <nav class="contents alert alert-primary float-md-right" id="contents" role="doc-toc">
  6. <p class="topic-title">Contents</p>
  7. <ul class="simple">
  8. <li><p><a class="reference internal" href="#all-you-need-to-know" id="toc-entry-1">All You Need to Know</a></p></li>
  9. <li><p><a class="reference internal" href="#what-s-nikola-and-what-can-you-do-with-it" id="toc-entry-2">What's Nikola and what can you do with it?</a></p></li>
  10. <li><p><a class="reference internal" href="#getting-help" id="toc-entry-3">Getting Help</a></p></li>
  11. <li><p><a class="reference internal" href="#why-static" id="toc-entry-4">Why Static?</a></p></li>
  12. <li><p><a class="reference internal" href="#components" id="toc-entry-5">Components</a></p></li>
  13. <li><p><a class="reference internal" href="#getting-started" id="toc-entry-6">Getting Started</a></p></li>
  14. <li><p><a class="reference internal" href="#creating-a-blog-post" id="toc-entry-7">Creating a Blog Post</a></p>
  15. <ul>
  16. <li><p><a class="reference internal" href="#metadata-fields" id="toc-entry-8">Metadata fields</a></p>
  17. <ul>
  18. <li><p><a class="reference internal" href="#basic" id="toc-entry-9">Basic</a></p></li>
  19. <li><p><a class="reference internal" href="#extra" id="toc-entry-10">Extra</a></p></li>
  20. </ul>
  21. </li>
  22. <li><p><a class="reference internal" href="#metadata-formats" id="toc-entry-11">Metadata formats</a></p>
  23. <ul>
  24. <li><p><a class="reference internal" href="#rest-style-comments" id="toc-entry-12">reST-style comments</a></p></li>
  25. <li><p><a class="reference internal" href="#two-file-format" id="toc-entry-13">Two-file format</a></p></li>
  26. <li><p><a class="reference internal" href="#jupyter-notebook-metadata" id="toc-entry-14">Jupyter Notebook metadata</a></p></li>
  27. <li><p><a class="reference internal" href="#yaml-metadata" id="toc-entry-15">YAML metadata</a></p></li>
  28. <li><p><a class="reference internal" href="#toml-metadata" id="toc-entry-16">TOML metadata</a></p></li>
  29. <li><p><a class="reference internal" href="#rest-docinfo" id="toc-entry-17">reST docinfo</a></p></li>
  30. <li><p><a class="reference internal" href="#pelican-markdown-metadata" id="toc-entry-18">Pelican/Markdown metadata</a></p></li>
  31. <li><p><a class="reference internal" href="#html-meta-tags" id="toc-entry-19">HTML meta tags</a></p></li>
  32. <li><p><a class="reference internal" href="#mapping-metadata-from-other-formats" id="toc-entry-20">Mapping metadata from other formats</a></p></li>
  33. </ul>
  34. </li>
  35. <li><p><a class="reference internal" href="#multilingual-posts" id="toc-entry-21">Multilingual posts</a></p></li>
  36. <li><p><a class="reference internal" href="#how-does-nikola-decide-where-posts-should-go" id="toc-entry-22">How does Nikola decide where posts should go?</a></p></li>
  37. <li><p><a class="reference internal" href="#the-new-post-command" id="toc-entry-23">The <code class="docutils literal">new_post</code> command</a></p></li>
  38. <li><p><a class="reference internal" href="#teasers" id="toc-entry-24">Teasers</a></p></li>
  39. <li><p><a class="reference internal" href="#drafts" id="toc-entry-25">Drafts</a></p></li>
  40. <li><p><a class="reference internal" href="#private-posts" id="toc-entry-26">Private Posts</a></p></li>
  41. <li><p><a class="reference internal" href="#featured-posts" id="toc-entry-27">Featured Posts</a></p></li>
  42. <li><p><a class="reference internal" href="#queuing-posts" id="toc-entry-28">Queuing Posts</a></p></li>
  43. <li><p><a class="reference internal" href="#post-types" id="toc-entry-29">Post Types</a></p></li>
  44. <li><p><a class="reference internal" href="#indexes" id="toc-entry-30">Indexes</a></p>
  45. <ul>
  46. <li><p><a class="reference internal" href="#settings" id="toc-entry-31">Settings</a></p></li>
  47. <li><p><a class="reference internal" href="#static-indexes" id="toc-entry-32">Static indexes</a></p></li>
  48. </ul>
  49. </li>
  50. <li><p><a class="reference internal" href="#post-taxonomy" id="toc-entry-33">Post taxonomy</a></p>
  51. <ul>
  52. <li><p><a class="reference internal" href="#tags" id="toc-entry-34">Tags</a></p></li>
  53. <li><p><a class="reference internal" href="#categories" id="toc-entry-35">Categories</a></p></li>
  54. <li><p><a class="reference internal" href="#configuring-tags-and-categories" id="toc-entry-36">Configuring tags and categories</a></p></li>
  55. </ul>
  56. </li>
  57. <li><p><a class="reference internal" href="#what-if-i-dont-want-a-blog" id="toc-entry-37">What if I don’t want a blog?</a></p></li>
  58. </ul>
  59. </li>
  60. <li><p><a class="reference internal" href="#creating-a-page" id="toc-entry-38">Creating a Page</a></p></li>
  61. <li><p><a class="reference internal" href="#supported-input-formats" id="toc-entry-39">Supported input formats</a></p>
  62. <ul>
  63. <li><p><a class="reference internal" href="#configuring-other-input-formats" id="toc-entry-40">Configuring other input formats</a></p>
  64. <ul>
  65. <li><p><a class="reference internal" href="#markdown" id="toc-entry-41">Markdown</a></p></li>
  66. <li><p><a class="reference internal" href="#jupyter-notebook" id="toc-entry-42">Jupyter Notebook</a></p></li>
  67. <li><p><a class="reference internal" href="#html" id="toc-entry-43">HTML</a></p></li>
  68. <li><p><a class="reference internal" href="#php" id="toc-entry-44">PHP</a></p></li>
  69. <li><p><a class="reference internal" href="#pandoc" id="toc-entry-45">Pandoc</a></p></li>
  70. </ul>
  71. </li>
  72. </ul>
  73. </li>
  74. <li><p><a class="reference internal" href="#shortcodes" id="toc-entry-46">Shortcodes</a></p>
  75. <ul>
  76. <li><p><a class="reference internal" href="#using-a-shortcode" id="toc-entry-47">Using a shortcode</a></p></li>
  77. <li><p><a class="reference internal" href="#built-in-shortcodes" id="toc-entry-48">Built-in shortcodes</a></p></li>
  78. <li><p><a class="reference internal" href="#community-shortcodes" id="toc-entry-49">Community shortcodes</a></p></li>
  79. <li><p><a class="reference internal" href="#template-based-shortcodes" id="toc-entry-50">Template-based shortcodes</a></p></li>
  80. </ul>
  81. </li>
  82. <li><p><a class="reference internal" href="#the-global-context-and-data-files" id="toc-entry-51">The Global Context and Data files</a></p></li>
  83. <li><p><a class="reference internal" href="#redirections" id="toc-entry-52">Redirections</a></p></li>
  84. <li><p><a class="reference internal" href="#configuration" id="toc-entry-53">Configuration</a></p></li>
  85. <li><p><a class="reference internal" href="#customizing-your-site" id="toc-entry-54">Customizing Your Site</a></p></li>
  86. <li><p><a class="reference internal" href="#fancy-dates" id="toc-entry-55">Fancy Dates</a></p></li>
  87. <li><p><a class="reference internal" href="#adding-files" id="toc-entry-56">Adding Files</a></p></li>
  88. <li><p><a class="reference internal" href="#custom-themes" id="toc-entry-57">Custom Themes</a></p></li>
  89. <li><p><a class="reference internal" href="#getting-extra-themes" id="toc-entry-58">Getting Extra Themes</a></p></li>
  90. <li><p><a class="reference internal" href="#deployment" id="toc-entry-59">Deployment</a></p>
  91. <ul>
  92. <li><p><a class="reference internal" href="#deploying-to-github" id="toc-entry-60">Deploying to GitHub</a></p></li>
  93. <li><p><a class="reference internal" href="#automated-rebuilds-github-actions-gitlab" id="toc-entry-61">Automated rebuilds (GitHub Actions, GitLab)</a></p></li>
  94. </ul>
  95. </li>
  96. <li><p><a class="reference internal" href="#comments" id="toc-entry-62">Comments</a></p></li>
  97. <li><p><a class="reference internal" href="#images-and-galleries" id="toc-entry-63">Images and Galleries</a></p>
  98. <ul>
  99. <li><p><a class="reference internal" href="#embedding-images" id="toc-entry-64">Embedding Images</a></p></li>
  100. </ul>
  101. </li>
  102. <li><p><a class="reference internal" href="#handling-exif-data" id="toc-entry-65">Handling EXIF Data</a></p>
  103. <ul>
  104. <li><p><a class="reference internal" href="#strip-all-exif-data" id="toc-entry-66">Strip all EXIF data</a></p></li>
  105. <li><p><a class="reference internal" href="#preserve-all-exif-data" id="toc-entry-67">Preserve all EXIF data</a></p></li>
  106. <li><p><a class="reference internal" href="#preserve-some-exif-data" id="toc-entry-68">Preserve some EXIF data</a></p></li>
  107. </ul>
  108. </li>
  109. <li><p><a class="reference internal" href="#handling-icc-profiles" id="toc-entry-69">Handling ICC Profiles</a></p></li>
  110. <li><p><a class="reference internal" href="#post-processing-filters" id="toc-entry-70">Post Processing Filters</a></p></li>
  111. <li><p><a class="reference internal" href="#optimizing-your-website" id="toc-entry-71">Optimizing Your Website</a></p></li>
  112. <li><p><a class="reference internal" href="#math" id="toc-entry-72">Math</a></p>
  113. <ul>
  114. <li><p><a class="reference internal" href="#configuration-1" id="toc-entry-73">Configuration</a></p></li>
  115. <li><p><a class="reference internal" href="#inline-usage" id="toc-entry-74">Inline usage</a></p></li>
  116. <li><p><a class="reference internal" href="#display-usage" id="toc-entry-75">Display usage</a></p></li>
  117. </ul>
  118. </li>
  119. <li><p><a class="reference internal" href="#restructuredtext-extensions" id="toc-entry-76">reStructuredText Extensions</a></p>
  120. <ul>
  121. <li><p><a class="reference internal" href="#includes" id="toc-entry-77">Includes</a></p></li>
  122. <li><p><a class="reference internal" href="#media" id="toc-entry-78">Media</a></p></li>
  123. <li><p><a class="reference internal" href="#youtube" id="toc-entry-79">YouTube</a></p></li>
  124. <li><p><a class="reference internal" href="#vimeo" id="toc-entry-80">Vimeo</a></p></li>
  125. <li><p><a class="reference internal" href="#soundcloud" id="toc-entry-81">Soundcloud</a></p></li>
  126. <li><p><a class="reference internal" href="#code" id="toc-entry-82">Code</a></p></li>
  127. <li><p><a class="reference internal" href="#listing" id="toc-entry-83">Listing</a></p></li>
  128. <li><p><a class="reference internal" href="#gist" id="toc-entry-84">Gist</a></p></li>
  129. <li><p><a class="reference internal" href="#thumbnails" id="toc-entry-85">Thumbnails</a></p></li>
  130. <li><p><a class="reference internal" href="#chart" id="toc-entry-86">Chart</a></p></li>
  131. <li><p><a class="reference internal" href="#doc" id="toc-entry-87">Doc</a></p></li>
  132. <li><p><a class="reference internal" href="#post-list" id="toc-entry-88">Post List</a></p></li>
  133. </ul>
  134. </li>
  135. <li><p><a class="reference internal" href="#importing-your-wordpress-site-into-nikola" id="toc-entry-89">Importing your WordPress site into Nikola</a></p>
  136. <ul>
  137. <li><p><a class="reference internal" href="#importing-to-a-custom-location-or-into-an-existing-site" id="toc-entry-90">Importing to a custom location or into an existing site</a></p></li>
  138. </ul>
  139. </li>
  140. <li><p><a class="reference internal" href="#using-twitter-cards" id="toc-entry-91">Using Twitter Cards</a></p></li>
  141. <li><p><a class="reference internal" href="#custom-plugins" id="toc-entry-92">Custom Plugins</a></p></li>
  142. <li><p><a class="reference internal" href="#getting-extra-plugins" id="toc-entry-93">Getting Extra Plugins</a></p></li>
  143. <li><p><a class="reference internal" href="#advanced-features" id="toc-entry-94">Advanced Features</a></p>
  144. <ul>
  145. <li><p><a class="reference internal" href="#debugging" id="toc-entry-95">Debugging</a></p></li>
  146. <li><p><a class="reference internal" href="#shell-tab-completion" id="toc-entry-96">Shell Tab Completion</a></p></li>
  147. </ul>
  148. </li>
  149. <li><p><a class="reference internal" href="#license" id="toc-entry-97">License</a></p></li>
  150. </ul>
  151. </nav>
  152. <section id="all-you-need-to-know">
  153. <h1><a class="toc-backref" href="#toc-entry-1" role="doc-backlink">All You Need to Know</a></h1>
  154. <p>After you have Nikola <a class="reference external" href="https://getnikola.com/getting-started.html">installed</a>:</p>
  155. <dl>
  156. <dt>Create an empty site (with a setup wizard):</dt>
  157. <dd><p><code class="docutils literal">nikola init mysite</code></p>
  158. <p>You can create a site with demo files in it with <code class="docutils literal">nikola init <span class="pre">--demo</span> mysite</code></p>
  159. <p>The rest of these commands have to be executed inside the new <code class="docutils literal">mysite</code> folder.</p>
  160. </dd>
  161. <dt>Create a post:</dt>
  162. <dd><p><code class="docutils literal">nikola new_post</code></p>
  163. </dd>
  164. <dt>Edit the post:</dt>
  165. <dd><p>The filename should be in the output of the previous command.
  166. You can also use <code class="docutils literal">nikola new_post <span class="pre">-e</span></code> to open an editor automatically.</p>
  167. </dd>
  168. <dt>Build the site:</dt>
  169. <dd><p><code class="docutils literal">nikola build</code></p>
  170. </dd>
  171. <dt>Start the test server and open a browser:</dt>
  172. <dd><p><code class="docutils literal">nikola serve <span class="pre">-b</span></code></p>
  173. </dd>
  174. </dl>
  175. <p>That should get you going. If you want to know more, this manual will always be here
  176. for you.</p>
  177. <p>DON'T READ THIS MANUAL. IF YOU NEED TO READ IT I FAILED, JUST USE THE THING.</p>
  178. <p>On the other hand, if anything about Nikola is not as obvious as it should be, by all
  179. means tell me about it :-)</p>
  180. </section>
  181. <section id="what-s-nikola-and-what-can-you-do-with-it">
  182. <h1><a class="toc-backref" href="#toc-entry-2" role="doc-backlink">What's Nikola and what can you do with it?</a></h1>
  183. <p>Nikola is a static website and blog generator. The very short explanation is
  184. that it takes some texts you wrote, and uses them to create a folder full
  185. of HTML files. If you upload that folder to a server, you will have a
  186. rather full-featured website, done with little effort.</p>
  187. <p>Its original goal is to create blogs, but it supports most kind of sites, and
  188. can be used as a CMS, as long as what you present to the user is your own content
  189. instead of something the user generates.</p>
  190. <p>Nikola can do:</p>
  191. <ul class="simple">
  192. <li><p>A blog (<a class="reference external" href="https://ralsina.me">example</a>)</p></li>
  193. <li><p>Your company's site</p></li>
  194. <li><p>Your personal site</p></li>
  195. <li><p>A software project's site (<a class="reference external" href="https://getnikola.com">example</a>)</p></li>
  196. <li><p>A book's site</p></li>
  197. </ul>
  198. <p>Since Nikola-based sites don't run any code on the server, there is no way to process
  199. user input in forms.</p>
  200. <p>Nikola can't do:</p>
  201. <ul class="simple">
  202. <li><p>Twitter</p></li>
  203. <li><p>Facebook</p></li>
  204. <li><p>An Issue tracker</p></li>
  205. <li><p>Anything with forms, really (except for <a class="reference internal" href="#comments">comments</a>!)</p></li>
  206. </ul>
  207. <p>Keep in mind that &quot;static&quot; doesn't mean <strong>boring</strong>. You can have animations
  208. or whatever fancy CSS3/HTML5 thingie you like. It only means all that HTML is
  209. generated already before being uploaded. On the other hand, Nikola sites will
  210. tend to be content-heavy. What Nikola is good at is at putting what you write
  211. out there.</p>
  212. </section>
  213. <section id="getting-help">
  214. <h1><a class="toc-backref" href="#toc-entry-3" role="doc-backlink">Getting Help</a></h1>
  215. <p class="lead"><a class="reference external" href="https://getnikola.com/contact.html">Get help here!</a></p>
  216. <p>TL;DR:</p>
  217. <ul class="simple">
  218. <li><p>You can file bugs at <a class="reference external" href="https://github.com/getnikola/nikola/issues">the issue tracker</a></p></li>
  219. <li><p>You can discuss Nikola at the <a class="reference external" href="https://groups.google.com/group/nikola-discuss">nikola-discuss google group</a></p></li>
  220. <li><p>You can subscribe to <a class="reference external" href="https://getnikola.com/blog">the Nikola Blog</a></p></li>
  221. <li><p>You can follow <a class="reference external" href="https://twitter.com/GetNikola">Nikola on Twitter</a></p></li>
  222. </ul>
  223. </section>
  224. <section id="why-static">
  225. <h1><a class="toc-backref" href="#toc-entry-4" role="doc-backlink">Why Static?</a></h1>
  226. <p>Most &quot;modern&quot; websites are <em>dynamic</em> in the sense that the contents of the site
  227. live in a database, and are converted into presentation-ready HTML only when a
  228. user wants to see the page. That's great. However, it presents some minor issues
  229. that static site generators try to solve.</p>
  230. <p>In a static site, the whole site, every page, <em>everything</em>, is created before
  231. the first user even sees it and uploaded to the server as a simple folder full
  232. of HTML files (and images, CSS, etc).</p>
  233. <p>So, let's see some reasons for using static sites:</p>
  234. <dl>
  235. <dt>Security</dt>
  236. <dd><p>Dynamic sites are prone to experience security issues. The solution for that
  237. is constant vigilance, keeping the software behind the site updated, and
  238. plain old good luck. The stack of software used to provide a static site,
  239. like those Nikola generates, is much smaller (Just a web server).</p>
  240. <p>A smaller software stack implies less security risk.</p>
  241. </dd>
  242. <dt>Obsolescence</dt>
  243. <dd><p>If you create a site using (for example) WordPress, what happens when WordPress
  244. releases a new version? You have to update your WordPress. That is not optional,
  245. because of security and support issues. If I release a new version of Nikola, and
  246. you don't update, <em>nothing</em> happens. You can continue to use the version you
  247. have now forever, no problems.</p>
  248. <p>Also, in the longer term, the very foundations of dynamic sites shift. Can you
  249. still deploy a blog software based on Django 0.96? What happens when your
  250. host stops supporting the PHP version you rely on? And so on.</p>
  251. <p>You may say those are long term issues, or that they won't matter for years. Well,
  252. I believe things should work forever, or as close to it as we can make them.
  253. Nikola's static output and its input files will work as long as you can install
  254. Python 3.7 or newer under Linux, Windows, or macOS and can find a server
  255. that sends files over HTTP. That's probably 10 or 15 years at least.</p>
  256. <p>Also, static sites are easily handled by the Internet Archive.</p>
  257. </dd>
  258. <dt>Cost and Performance</dt>
  259. <dd><p>On dynamic sites, every time a reader wants a page, a whole lot of database
  260. queries are made. Then a whole pile of code chews that data, and HTML is
  261. produced, which is sent to the user. All that requires CPU and memory.</p>
  262. <p>On a static site, the highly optimized HTTP server reads the file from disk
  263. (or, if it's a popular file, from disk cache), and sends it to the user. You could
  264. probably serve a bazillion (technical term) page views from a phone using
  265. static sites.</p>
  266. </dd>
  267. <dt>Lock-in</dt>
  268. <dd><p>On server-side blog platforms, sometimes you can't export your own data, or
  269. it's in strange formats you can't use in other services. I have switched
  270. blogging platforms from Advogato to PyCs to two homebrew systems, to Nikola,
  271. and have never lost a file, a URL, or a comment. That's because I have <em>always</em>
  272. had my own data in a format of my choice.</p>
  273. <p>With Nikola, you own your files, and you can do anything with them.</p>
  274. </dd>
  275. </dl>
  276. </section>
  277. <section id="components">
  278. <h1><a class="toc-backref" href="#toc-entry-5" role="doc-backlink">Components</a></h1>
  279. <p>Nikola provides the following features:</p>
  280. <ul class="simple">
  281. <li><p>Blog support, including:</p>
  282. <ul>
  283. <li><p>Indexes</p></li>
  284. <li><p>RSS and Atom feeds</p></li>
  285. <li><p>Tags and categories, with pages and feeds</p></li>
  286. <li><p>Author pages and feeds (not generated if <code class="docutils literal">ENABLE_AUTHOR_PAGES</code> is set to <code class="docutils literal">False</code> or there is only one author)</p></li>
  287. <li><p>Archives with custom granularity (yearly or monthly)</p></li>
  288. <li><p><a class="reference internal" href="#comments">Comments</a></p></li>
  289. </ul>
  290. </li>
  291. <li><p>Static pages (not part of the blog)</p></li>
  292. <li><p><a class="reference internal" href="#math">Math</a> rendering (via MathJax)</p></li>
  293. <li><p>Custom output paths for generated pages</p></li>
  294. <li><p>Pretty URLs (without <code class="docutils literal">.html</code>) that don’t need web server support</p></li>
  295. <li><p>Easy page template customization</p></li>
  296. <li><p>Internationalization support (my own blog is English and Spanish)</p></li>
  297. <li><p>Sitemap generation (for search engines)</p></li>
  298. <li><p>Custom deployment (if it’s a command, you can use it)</p></li>
  299. <li><p>GitHub Pages deployment</p></li>
  300. <li><p>Themes, easy appearance customization</p></li>
  301. <li><p><a class="reference external" href="#supported-input-formats">Multiple input formats</a>, including reStructuredText and Markdown</p></li>
  302. <li><p>Easy-to-create image galleries</p></li>
  303. <li><p>Image thumbnail generation</p></li>
  304. <li><p>Support for displaying source code listings</p></li>
  305. <li><p>Custom search</p></li>
  306. <li><p>Asset (CSS/JS) bundling</p></li>
  307. <li><p>gzip compression (for sending via your web server)</p></li>
  308. <li><p>Open Graph, Twitter Cards</p></li>
  309. <li><p>Hyphenation</p></li>
  310. <li><p>Custom <a class="reference internal" href="#post-processing-filters">post processing filters</a> (eg. for minifying files or better typography)</p></li>
  311. </ul>
  312. </section>
  313. <section id="getting-started">
  314. <h1><a class="toc-backref" href="#toc-entry-6" role="doc-backlink">Getting Started</a></h1>
  315. <p class="lead">To set Nikola up and create your first site, read the <a class="reference external" href="https://getnikola.com/getting-started.html">Getting Started Guide</a>.</p>
  316. </section>
  317. <section id="creating-a-blog-post">
  318. <h1><a class="toc-backref" href="#toc-entry-7" role="doc-backlink">Creating a Blog Post</a></h1>
  319. <aside class="sidebar">
  320. <p class="sidebar-title">Magic Links</p>
  321. <p>You will want to do things like &quot;link from one post to another&quot; or &quot;link to an image gallery&quot;,
  322. etc. Sure, you can just figure out the URLs for each thing and use that. Or you can use
  323. Nikola's special link URLs. Those are done using the syntax <code class="docutils literal"><span class="pre">link://kind/name</span></code> and
  324. a full list of the included ones is <a class="reference external" href="link://slug/path-handlers">here</a> (BTW, I linked
  325. to that using <code class="docutils literal"><span class="pre">link://slug/path-handlers</span></code>).</p>
  326. <p>Note that magic links with spaces won’t work with some input formats (eg.
  327. reST), so you should use slugs there (eg. <code class="docutils literal"><span class="pre">link://tag/some-tag</span></code> instead of
  328. <code class="docutils literal"><span class="pre">link://tag/Some</span> Tag</code>)</p>
  329. </aside>
  330. <p>To create a new post, the easiest way is to run <code class="docutils literal">nikola new_post</code>. You will
  331. be asked for a title for your post, and it will tell you where the post's file
  332. is located.</p>
  333. <p>By default, that file will contain also some extra information about your post (&quot;the metadata&quot;).
  334. It can be placed in a separate file by using the <code class="docutils literal"><span class="pre">-2</span></code> option, but it's generally
  335. easier to keep it in a single location.</p>
  336. <p>The contents of your post have to be written (by default) in <a class="reference external" href="https://docutils.sourceforge.io/">reStructuredText</a>
  337. but you can use a lot of different markups using the <code class="docutils literal"><span class="pre">-f</span></code> option.</p>
  338. <p>Currently, Nikola supports reStructuredText, Markdown, Jupyter Notebooks, HTML as input,
  339. can also use Pandoc for conversion, and has support for BBCode, CreoleWiki, txt2tags, Textile
  340. and more via plugins — for more details, read the <a class="reference external" href="#multiple-input-formats">input format documentation</a>.
  341. You can learn reStructuredText syntax with the <a class="reference external" href="https://getnikola.com/quickstart.html">reST quickstart</a>.</p>
  342. <p>Please note that Nikola does not support encodings other than UTF-8. Make sure
  343. to convert your input files to that encoding to avoid issues. It will prevent
  344. bugs, and Nikola will write UTF-8 output anyway.</p>
  345. <p>You can control what markup compiler is used for each file extension with the <code class="docutils literal">COMPILERS</code>
  346. option. The default configuration expects them to be placed in <code class="docutils literal">posts</code> but that can be
  347. changed (see below, the <code class="docutils literal">POSTS</code> and <code class="docutils literal">PAGES</code> options)</p>
  348. <p>This is how it works:</p>
  349. <pre class="code console"><a name="rest_code_27f80e9a519343b59b7e590691a9d5b9-1"></a><span class="gp">$</span> nikola new_post
  350. <a name="rest_code_27f80e9a519343b59b7e590691a9d5b9-2"></a><span class="go">Creating New Post</span>
  351. <a name="rest_code_27f80e9a519343b59b7e590691a9d5b9-3"></a><span class="go">-----------------</span>
  352. <a name="rest_code_27f80e9a519343b59b7e590691a9d5b9-4"></a>
  353. <a name="rest_code_27f80e9a519343b59b7e590691a9d5b9-5"></a><span class="go">Title: How to make money</span>
  354. <a name="rest_code_27f80e9a519343b59b7e590691a9d5b9-6"></a><span class="go">Scanning posts....done!</span>
  355. <a name="rest_code_27f80e9a519343b59b7e590691a9d5b9-7"></a><span class="go">INFO: new_post: Your post&#39;s text is at: posts/how-to-make-money.rst</span>
  356. </pre><p>The content of that file is as follows:</p>
  357. <pre class="code restructuredtext"><a name="rest_code_d333d88e8ec84873a87f6e2d428162fe-1"></a><span class="cp">.. title: How to make money</span>
  358. <a name="rest_code_d333d88e8ec84873a87f6e2d428162fe-2"></a><span class="cp">.. slug: how-to-make-money</span>
  359. <a name="rest_code_d333d88e8ec84873a87f6e2d428162fe-3"></a><span class="cp">.. date: 2012-09-15 19:52:05 UTC</span>
  360. <a name="rest_code_d333d88e8ec84873a87f6e2d428162fe-4"></a><span class="cp">.. tags:</span>
  361. <a name="rest_code_d333d88e8ec84873a87f6e2d428162fe-5"></a><span class="cp">.. link:</span>
  362. <a name="rest_code_d333d88e8ec84873a87f6e2d428162fe-6"></a><span class="cp">.. description:</span>
  363. <a name="rest_code_d333d88e8ec84873a87f6e2d428162fe-7"></a><span class="cp">.. type: text</span>
  364. <a name="rest_code_d333d88e8ec84873a87f6e2d428162fe-8"></a>
  365. <a name="rest_code_d333d88e8ec84873a87f6e2d428162fe-9"></a>Write your post here.
  366. </pre><p>You can edit these files with your favorite text editor, and once you are happy
  367. with the contents, generate the pages using <code class="docutils literal">nikola build</code>.</p>
  368. <p>The post page is generated by default using the <code class="docutils literal">post.tmpl</code> template, which you can use
  369. to customize the output. You can also customize paths and the template filename
  370. itself — see <cite>How does Nikola decide where posts should go?</cite></p>
  371. <section id="metadata-fields">
  372. <h2><a class="toc-backref" href="#toc-entry-8" role="doc-backlink">Metadata fields</a></h2>
  373. <p>Nikola supports many metadata fields in posts. All of them are
  374. translatable and almost all are optional.</p>
  375. <section id="basic">
  376. <h3><a class="toc-backref" href="#toc-entry-9" role="doc-backlink">Basic</a></h3>
  377. <dl>
  378. <dt>title</dt>
  379. <dd><p>Title of the post. Using HTML/math in titles is not supported/recommended.
  380. If not specified, the file name will be used.</p>
  381. </dd>
  382. <dt>slug</dt>
  383. <dd><p>Slug of the post. Used as the last component of the page URL. We recommend
  384. and default to using a restricted character set (<code class="docutils literal"><span class="pre">a-z0-9-_</span></code>) because
  385. other symbols may cause issues in URLs. If not specified, the file name will be used.</p>
  386. <p>So, if the slug is &quot;the-slug&quot; the page generated would be &quot;the-slug.html&quot; or
  387. &quot;the-slug/index.html&quot; (if you have the pretty URLs option enabled)</p>
  388. <p>One special case is setting the slug to &quot;index&quot;. This means the page generated
  389. would be &quot;some_folder/index.html&quot;, which means it will be open for the URL
  390. that ends in &quot;some_folder&quot; or &quot;some_folder/&quot;.</p>
  391. <p>This is useful in some cases, in others may cause conflicts with other pages
  392. Nikola generates (like blog indexes) and as a side effect it disables
  393. &quot;pretty URLs&quot; for this page. So use with care.</p>
  394. </dd>
  395. <dt>date</dt>
  396. <dd><p>Date of the post, defaults to now. Multiple date formats are accepted.
  397. Adding a timezone is recommended. (required for posts)</p>
  398. </dd>
  399. <dt>tags</dt>
  400. <dd><p>Comma-separated tags of the post.</p>
  401. </dd>
  402. <dt>status</dt>
  403. <dd><p>Can be set to <code class="docutils literal">published</code> (default), <code class="docutils literal">featured</code>, <code class="docutils literal">draft</code>, or <code class="docutils literal">private</code>.</p>
  404. </dd>
  405. <dt>has_math</dt>
  406. <dd><p>If set to <code class="docutils literal">true</code> or <code class="docutils literal">yes</code>, MathJax resp. KaTeX support is enabled
  407. for this post.</p>
  408. </dd>
  409. <dt>category</dt>
  410. <dd><p>Like tags, except each post can have only one, and they usually have
  411. more descriptive names.</p>
  412. </dd>
  413. <dt>guid</dt>
  414. <dd><p>String used as GUID in RSS feeds and as ID in Atom feeds instead of the
  415. permalink.</p>
  416. </dd>
  417. <dt>link</dt>
  418. <dd><p>Link to original source for content. May be displayed by some themes.</p>
  419. </dd>
  420. <dt>description</dt>
  421. <dd><p>Description of the post. Used in <code class="docutils literal">&lt;meta&gt;</code> tags for SEO.</p>
  422. </dd>
  423. <dt>type</dt>
  424. <dd><p>Type of the post. See <a class="reference internal" href="#post-types">Post Types</a> for details. Whatever you set here
  425. (prepended with <code class="docutils literal">post-</code>) will become a CSS class of the <code class="docutils literal">&lt;article&gt;</code>
  426. element for this post. Defaults to <code class="docutils literal">text</code> (resulting in a <code class="docutils literal"><span class="pre">post-text</span></code>
  427. class)</p>
  428. </dd>
  429. </dl>
  430. </section>
  431. <section id="extra">
  432. <h3><a class="toc-backref" href="#toc-entry-10" role="doc-backlink">Extra</a></h3>
  433. <dl>
  434. <dt>author</dt>
  435. <dd><p>Author of the post, will be used in the RSS feed and possibly in the post
  436. display (theme-dependent)</p>
  437. </dd>
  438. <dt>enclosure</dt>
  439. <dd><p>Add an enclosure to this post when it's used in RSS. See <a class="reference external" href="https://en.wikipedia.org/wiki/RSS_enclosure">more information about enclosures</a></p>
  440. </dd>
  441. <dt>data</dt>
  442. <dd><p>Path to an external data file (JSON/YAML/TOML dictionary), relative to <code class="docutils literal">conf.py</code>.
  443. Its keys are available for templates as <code class="docutils literal"><span class="pre">post.data('key')</span></code>.</p>
  444. <p>Translated posts can have different values for this field, and the correct one will be
  445. used.</p>
  446. <p>See <a class="reference internal" href="#the-global-context-and-data-files">The Global Context and Data files</a> for more details. This is
  447. especially useful used in combination with <a class="reference internal" href="#shortcodes">shortcodes</a>.</p>
  448. </dd>
  449. <dt>filters</dt>
  450. <dd><p>See the <a class="reference internal" href="#post-processing-filters">Post Processing Filters</a> section.</p>
  451. </dd>
  452. <dt>hidetitle</dt>
  453. <dd><p>Set &quot;True&quot; if you do not want to see the <strong>page</strong> title as a
  454. heading of the output html file (does not work for posts).</p>
  455. </dd>
  456. <dt>hyphenate</dt>
  457. <dd><p>Set &quot;True&quot; if you want this document to be hyphenated even if you have
  458. hyphenation disabled by default.</p>
  459. </dd>
  460. <dt>nocomments</dt>
  461. <dd><p>Set to &quot;True&quot; to disable comments.</p>
  462. </dd>
  463. <dt>pretty_url</dt>
  464. <dd><p>Set to &quot;False&quot; to disable pretty URL for this page.</p>
  465. </dd>
  466. <dt>previewimage</dt>
  467. <dd><p>Designate a preview or other representative image path relative to BASE_URL
  468. for use with Open Graph for posts. Adds the image when sharing on social
  469. media, feeds, and many other uses.</p>
  470. <pre class="code restructuredtext"><a name="rest_code_97a673e5affa4cf4b57957e3e858b667-1"></a><span class="cp">.. previewimage: /images/looks_great_on_facebook.png</span>
  471. </pre><p>If a post has no <cite>previewimage</cite> it will try to use the <cite>DEFAULT_PREVIEW_IMAGE</cite>
  472. option from the configuration.</p>
  473. <p>The image can be of any size and dimension (services will crop and adapt)
  474. but should less than 1 MB and be larger than 300x300 (ideally 600x600).</p>
  475. <p>This image is displayed by <code class="docutils literal">bootblog4</code> for featured posts (see <a class="reference internal" href="#featured-posts">Featured
  476. Posts</a> for details).</p>
  477. </dd>
  478. <dt>template</dt>
  479. <dd><p>Change the template used to render this page/post specific page. That
  480. template needs to either be part of the theme, or be placed in a
  481. <code class="docutils literal">templates/</code> folder inside your site.</p>
  482. <pre class="code restructuredtext"><a name="rest_code_b80b58639b8041c3924a6ca547364653-1"></a><span class="cp">.. template: foobar.tmpl</span>
  483. </pre></dd>
  484. <dt>updated</dt>
  485. <dd><p>The last time this post was updated, defaults to the post’s <code class="docutils literal">date</code>
  486. metadata value. It is not displayed by default in most themes, including
  487. the defaults — you can use <code class="docutils literal">post.formatted_updated(date_format)</code> (and
  488. perhaps check <code class="docutils literal">if post.updated != post.date</code>) in your post template to
  489. show it.</p>
  490. </dd>
  491. </dl>
  492. <p>To add these metadata fields to all new posts by default, you can set the
  493. variable <code class="docutils literal">ADDITIONAL_METADATA</code> in your configuration. For example, you can
  494. add the author metadata to all new posts by default, by adding the following
  495. to your configuration:</p>
  496. <pre class="code python"><a name="rest_code_50d82e8fa05a410d9742622ce1b51a2f-1"></a><span class="n">ADDITIONAL_METADATA</span> <span class="o">=</span> <span class="p">{</span>
  497. <a name="rest_code_50d82e8fa05a410d9742622ce1b51a2f-2"></a> <span class="s1">&#39;author&#39;</span><span class="p">:</span> <span class="s1">&#39;John Doe&#39;</span>
  498. <a name="rest_code_50d82e8fa05a410d9742622ce1b51a2f-3"></a><span class="p">}</span>
  499. </pre><dl>
  500. <dt>url_type</dt>
  501. <dd><p>Change the URL_TYPE setting for the given page only. Useful for eg. error
  502. pages which cannot use relative URLs.</p>
  503. <pre class="code restructuredtext"><a name="rest_code_2854eb3509c24c4bbe597eaaacef8728-1"></a><span class="cp">.. url_type: full_path</span>
  504. </pre></dd>
  505. </dl>
  506. </section>
  507. </section>
  508. <section id="metadata-formats">
  509. <h2><a class="toc-backref" href="#toc-entry-11" role="doc-backlink">Metadata formats</a></h2>
  510. <p>Metadata can be in different formats.
  511. Current Nikola versions experimentally supports other metadata formats that make it more compatible with
  512. other static site generators. The currently supported metadata formats are:</p>
  513. <ul class="simple">
  514. <li><p>reST-style comments (<code class="docutils literal">.. name: value</code> — default format)</p></li>
  515. <li><p>Two-file format (reST-style, YAML, TOML)</p></li>
  516. <li><p>Jupyter Notebook metadata</p></li>
  517. <li><p>YAML, between <code class="docutils literal"><span class="pre">---</span></code> (Jekyll, Hugo)</p></li>
  518. <li><p>TOML, between <code class="docutils literal">+++</code> (Hugo)</p></li>
  519. <li><p>reST docinfo (Pelican)</p></li>
  520. <li><p>Markdown metadata extension (Pelican)</p></li>
  521. <li><p>HTML meta tags (Pelican)</p></li>
  522. </ul>
  523. <p>You can add arbitrary meta fields in any format.</p>
  524. <p>When you create new posts, by default the metadata will be created as reST style comments.
  525. If you prefer a different format, you can set the <code class="docutils literal">METADATA_FORMAT</code> to one of these values:</p>
  526. <ul class="simple">
  527. <li><p><code class="docutils literal">&quot;Nikola&quot;</code>: reST comments, wrapped in a HTML comment if needed (default)</p></li>
  528. <li><p><code class="docutils literal">&quot;YAML&quot;</code>: YAML wrapped in &quot;---&quot;</p></li>
  529. <li><p><code class="docutils literal">&quot;TOML&quot;</code>: TOML wrapped in &quot;+++&quot;</p></li>
  530. <li><p><code class="docutils literal">&quot;Pelican&quot;</code>: Native markdown metadata or reST docinfo fields. Nikola style for other formats.</p></li>
  531. </ul>
  532. <section id="rest-style-comments">
  533. <h3><a class="toc-backref" href="#toc-entry-12" role="doc-backlink">reST-style comments</a></h3>
  534. <p>The “traditional” and default meta field format is:</p>
  535. <pre class="code text"><a name="rest_code_f90ce434a9874e66ba5689c7d1bab7ad-1"></a>.. name: value
  536. </pre><p>If you are not using reStructuredText, make sure the fields are in a HTML comment in output.</p>
  537. <p>Also, note that this format does not support any multi-line values. Try YAML or reST docinfo if you need those.</p>
  538. </section>
  539. <section id="two-file-format">
  540. <h3><a class="toc-backref" href="#toc-entry-13" role="doc-backlink">Two-file format</a></h3>
  541. <p>Meta information can also be specified in separate <code class="docutils literal">.meta</code> files. Those support reST-style metadata, with names and custom fields. They look like the beginning of our reST files:</p>
  542. <pre class="code text"><a name="rest_code_1022c20cc60e4916ba5a84038643797e-1"></a>.. title: How to make money
  543. <a name="rest_code_1022c20cc60e4916ba5a84038643797e-2"></a>.. slug: how-to-make-money
  544. <a name="rest_code_1022c20cc60e4916ba5a84038643797e-3"></a>.. date: 2012-09-15 19:52:05 UTC
  545. </pre><p>You can also use YAML or TOML metadata inside those (with the appropriate markers).</p>
  546. </section>
  547. <section id="jupyter-notebook-metadata">
  548. <h3><a class="toc-backref" href="#toc-entry-14" role="doc-backlink">Jupyter Notebook metadata</a></h3>
  549. <p>Jupyter posts can store meta information inside <code class="docutils literal">.ipynb</code> files by using the <code class="docutils literal">nikola</code> key inside notebook metadata. It can be edited by using <em>Edit → Edit Notebook Metadata</em> in Jupyter. Note that values are currently only strings. Sample metadata (Jupyter-specific information omitted):</p>
  550. <pre class="code json"><a name="rest_code_9647fc2add0344ac9e8656918e2ea2d4-1"></a><span class="p">{</span>
  551. <a name="rest_code_9647fc2add0344ac9e8656918e2ea2d4-2"></a> <span class="nt">&quot;nikola&quot;</span><span class="p">:</span> <span class="p">{</span>
  552. <a name="rest_code_9647fc2add0344ac9e8656918e2ea2d4-3"></a> <span class="nt">&quot;title&quot;</span><span class="p">:</span> <span class="s2">&quot;How to make money&quot;</span><span class="p">,</span>
  553. <a name="rest_code_9647fc2add0344ac9e8656918e2ea2d4-4"></a> <span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;how-to-make-money&quot;</span><span class="p">,</span>
  554. <a name="rest_code_9647fc2add0344ac9e8656918e2ea2d4-5"></a> <span class="nt">&quot;date&quot;</span><span class="p">:</span> <span class="s2">&quot;2012-09-15 19:52:05 UTC&quot;</span>
  555. <a name="rest_code_9647fc2add0344ac9e8656918e2ea2d4-6"></a> <span class="p">}</span>
  556. <a name="rest_code_9647fc2add0344ac9e8656918e2ea2d4-7"></a><span class="p">}</span>
  557. </pre></section>
  558. <section id="yaml-metadata">
  559. <h3><a class="toc-backref" href="#toc-entry-15" role="doc-backlink">YAML metadata</a></h3>
  560. <p>YAML metadata should be wrapped by a <code class="docutils literal"><span class="pre">---</span></code> separator (three dashes) and in that case, the usual YAML syntax is used:</p>
  561. <pre class="code yaml"><a name="rest_code_f4e6fbfb07d240f18bca1ee54c4bbead-1"></a><span class="nn">---</span>
  562. <a name="rest_code_f4e6fbfb07d240f18bca1ee54c4bbead-2"></a><span class="nt">title</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">How to make money</span>
  563. <a name="rest_code_f4e6fbfb07d240f18bca1ee54c4bbead-3"></a><span class="nt">slug</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">how-to-make-money</span>
  564. <a name="rest_code_f4e6fbfb07d240f18bca1ee54c4bbead-4"></a><span class="nt">date</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">2012-09-15 19:52:05 UTC</span>
  565. <a name="rest_code_f4e6fbfb07d240f18bca1ee54c4bbead-5"></a><span class="nn">---</span>
  566. </pre></section>
  567. <section id="toml-metadata">
  568. <h3><a class="toc-backref" href="#toc-entry-16" role="doc-backlink">TOML metadata</a></h3>
  569. <p>TOML metadata should be wrapped by a &quot;+++&quot; separator (three plus signs) and in that case, the usual TOML syntax is used:</p>
  570. <pre class="code yaml"><a name="rest_code_c9318f4484674b5ab527be3ebdc1516d-1"></a><span class="l l-Scalar l-Scalar-Plain">+++</span>
  571. <a name="rest_code_c9318f4484674b5ab527be3ebdc1516d-2"></a><span class="l l-Scalar l-Scalar-Plain">title = &quot;How to make money&quot;</span>
  572. <a name="rest_code_c9318f4484674b5ab527be3ebdc1516d-3"></a><span class="l l-Scalar l-Scalar-Plain">slug = &quot;how-to-make-money&quot;</span>
  573. <a name="rest_code_c9318f4484674b5ab527be3ebdc1516d-4"></a><span class="l l-Scalar l-Scalar-Plain">date = &quot;2012-09-15 19:52:05 UTC&quot;</span>
  574. <a name="rest_code_c9318f4484674b5ab527be3ebdc1516d-5"></a><span class="l l-Scalar l-Scalar-Plain">+++</span>
  575. </pre></section>
  576. <section id="rest-docinfo">
  577. <h3><a class="toc-backref" href="#toc-entry-17" role="doc-backlink">reST docinfo</a></h3>
  578. <p>Nikola can extract metadata from reStructuredText docinfo fields and the document itself, too:</p>
  579. <pre class="code restructuredtext"><a name="rest_code_adc136ef3f8e4caf9316c947f102584d-1"></a><span class="gh">How to make money</span>
  580. <a name="rest_code_adc136ef3f8e4caf9316c947f102584d-2"></a><span class="gh">=================</span>
  581. <a name="rest_code_adc136ef3f8e4caf9316c947f102584d-3"></a>
  582. <a name="rest_code_adc136ef3f8e4caf9316c947f102584d-4"></a><span class="nc">:slug:</span> how-to-make-money
  583. <a name="rest_code_adc136ef3f8e4caf9316c947f102584d-5"></a><span class="nc">:date:</span> 2012-09-15 19:52:05 UTC
  584. </pre><p>To do this, you need <code class="docutils literal">USE_REST_DOCINFO_METADATA = True</code> in your <code class="docutils literal">conf.py</code>,
  585. and Nikola will hide the docinfo fields in the output if you set
  586. <code class="docutils literal">HIDE_REST_DOCINFO = True</code>.</p>
  587. <aside class="admonition note">
  588. <p class="admonition-title">Note</p>
  589. <p>Keys are converted to lowercase automatically.</p>
  590. <p>This setting also means that the first heading in a post will be removed
  591. and considered a title. This is important if you’re mixing metadata
  592. styles. This can be solved by putting a reST comment before your title.</p>
  593. </aside>
  594. </section>
  595. <section id="pelican-markdown-metadata">
  596. <h3><a class="toc-backref" href="#toc-entry-18" role="doc-backlink">Pelican/Markdown metadata</a></h3>
  597. <p>Markdown Metadata (Pelican-style) only works in Markdown files, and requires the <code class="docutils literal">markdown.extensions.meta</code> extension
  598. (see <a class="reference external" href="#markdown">MARKDOWN_EXTENSIONS</a>). The exact format is described in
  599. the <a class="reference external" href="https://python-markdown.github.io/extensions/meta_data/">markdown metadata extension docs.</a></p>
  600. <pre class="code text"><a name="rest_code_7439c987f2344616a3b2cbb1a6cebfa9-1"></a>title: How to make money
  601. <a name="rest_code_7439c987f2344616a3b2cbb1a6cebfa9-2"></a>slug: how-to-make-money
  602. <a name="rest_code_7439c987f2344616a3b2cbb1a6cebfa9-3"></a>date: 2012-09-15 19:52:05 UTC
  603. </pre><p>Note that keys are converted to lowercase automatically.</p>
  604. </section>
  605. <section id="html-meta-tags">
  606. <h3><a class="toc-backref" href="#toc-entry-19" role="doc-backlink">HTML meta tags</a></h3>
  607. <p>For HTML source files, metadata will be extracted from <code class="docutils literal">meta</code> tags, and the title from the <code class="docutils literal">title</code> tag.
  608. Following Pelican's behaviour, tags can be put in a &quot;tags&quot; meta tag or in a &quot;keywords&quot; meta tag. Example:</p>
  609. <pre class="code html"><a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-1"></a><span class="p">&lt;</span><span class="nt">html</span><span class="p">&gt;</span>
  610. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-2"></a> <span class="p">&lt;</span><span class="nt">head</span><span class="p">&gt;</span>
  611. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-3"></a> <span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span>My super title<span class="p">&lt;/</span><span class="nt">title</span><span class="p">&gt;</span>
  612. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-4"></a> <span class="p">&lt;</span><span class="nt">meta</span> <span class="na">name</span><span class="o">=</span><span class="s">&quot;tags&quot;</span> <span class="na">content</span><span class="o">=</span><span class="s">&quot;thats, awesome&quot;</span> <span class="p">/&gt;</span>
  613. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-5"></a> <span class="p">&lt;</span><span class="nt">meta</span> <span class="na">name</span><span class="o">=</span><span class="s">&quot;date&quot;</span> <span class="na">content</span><span class="o">=</span><span class="s">&quot;2012-07-09 22:28&quot;</span> <span class="p">/&gt;</span>
  614. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-6"></a> <span class="p">&lt;</span><span class="nt">meta</span> <span class="na">name</span><span class="o">=</span><span class="s">&quot;modified&quot;</span> <span class="na">content</span><span class="o">=</span><span class="s">&quot;2012-07-10 20:14&quot;</span> <span class="p">/&gt;</span>
  615. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-7"></a> <span class="p">&lt;</span><span class="nt">meta</span> <span class="na">name</span><span class="o">=</span><span class="s">&quot;category&quot;</span> <span class="na">content</span><span class="o">=</span><span class="s">&quot;yeah&quot;</span> <span class="p">/&gt;</span>
  616. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-8"></a> <span class="p">&lt;</span><span class="nt">meta</span> <span class="na">name</span><span class="o">=</span><span class="s">&quot;authors&quot;</span> <span class="na">content</span><span class="o">=</span><span class="s">&quot;Conan Doyle&quot;</span> <span class="p">/&gt;</span>
  617. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-9"></a> <span class="p">&lt;</span><span class="nt">meta</span> <span class="na">name</span><span class="o">=</span><span class="s">&quot;summary&quot;</span> <span class="na">content</span><span class="o">=</span><span class="s">&quot;Short version for index and feeds&quot;</span> <span class="p">/&gt;</span>
  618. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-10"></a> <span class="p">&lt;/</span><span class="nt">head</span><span class="p">&gt;</span>
  619. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-11"></a> <span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
  620. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-12"></a> This is the content of my super blog post.
  621. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-13"></a> <span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
  622. <a name="rest_code_4498a64614fc41caa8f76bb21d7c3d45-14"></a><span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span>
  623. </pre></section>
  624. <section id="mapping-metadata-from-other-formats">
  625. <h3><a class="toc-backref" href="#toc-entry-20" role="doc-backlink">Mapping metadata from other formats</a></h3>
  626. <p>If you import posts from other engines, those may not work with Nikola out of the box due to differing names. However, you can create a mapping to convert meta field names from those formats into what Nikola expects.</p>
  627. <p>For Pelican, use:</p>
  628. <pre class="code python"><a name="rest_code_e726dc97319445be881e170a226ccf89-1"></a><span class="n">METADATA_MAPPING</span> <span class="o">=</span> <span class="p">{</span>
  629. <a name="rest_code_e726dc97319445be881e170a226ccf89-2"></a> <span class="s2">&quot;rest_docinfo&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;summary&quot;</span><span class="p">:</span> <span class="s2">&quot;description&quot;</span><span class="p">,</span> <span class="s2">&quot;modified&quot;</span><span class="p">:</span> <span class="s2">&quot;updated&quot;</span><span class="p">},</span>
  630. <a name="rest_code_e726dc97319445be881e170a226ccf89-3"></a> <span class="s2">&quot;markdown_metadata&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;summary&quot;</span><span class="p">:</span> <span class="s2">&quot;description&quot;</span><span class="p">,</span> <span class="s2">&quot;modified&quot;</span><span class="p">:</span> <span class="s2">&quot;updated&quot;</span><span class="p">}</span>
  631. <a name="rest_code_e726dc97319445be881e170a226ccf89-4"></a> <span class="s2">&quot;html_metadata&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;summary&quot;</span><span class="p">:</span> <span class="s2">&quot;description&quot;</span><span class="p">,</span> <span class="s2">&quot;modified&quot;</span><span class="p">:</span> <span class="s2">&quot;updated&quot;</span><span class="p">}</span>
  632. <a name="rest_code_e726dc97319445be881e170a226ccf89-5"></a><span class="p">}</span>
  633. </pre><p>For Hugo, use:</p>
  634. <pre class="code python"><a name="rest_code_fd7d31032d31435784f80d60617c05a5-1"></a><span class="n">METADATA_MAPPING</span> <span class="o">=</span> <span class="p">{</span>
  635. <a name="rest_code_fd7d31032d31435784f80d60617c05a5-2"></a> <span class="s2">&quot;yaml&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;lastmod&quot;</span><span class="p">:</span> <span class="s2">&quot;updated&quot;</span><span class="p">},</span>
  636. <a name="rest_code_fd7d31032d31435784f80d60617c05a5-3"></a> <span class="s2">&quot;toml&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;lastmod&quot;</span><span class="p">:</span> <span class="s2">&quot;updated&quot;</span><span class="p">}</span>
  637. <a name="rest_code_fd7d31032d31435784f80d60617c05a5-4"></a><span class="p">}</span>
  638. </pre><p>The following source names are supported: <code class="docutils literal">yaml</code>, <code class="docutils literal">toml</code>, <code class="docutils literal">rest_docinfo</code>, <code class="docutils literal">markdown_metadata</code>.</p>
  639. <p>Additionally, you can use <code class="docutils literal">METADATA_VALUE_MAPPING</code> to perform any extra conversions on metadata for <strong>all</strong> posts of a given format (<code class="docutils literal">nikola</code> metadata is also supported). A few examples:</p>
  640. <pre class="code python"><a name="rest_code_37ab99d321f34e6a81a1c6429c22ebcb-1"></a><span class="n">METADATA_VALUE_MAPPING</span> <span class="o">=</span> <span class="p">{</span>
  641. <a name="rest_code_37ab99d321f34e6a81a1c6429c22ebcb-2"></a> <span class="s2">&quot;yaml&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;keywords&quot;</span><span class="p">:</span> <span class="k">lambda</span> <span class="n">value</span><span class="p">:</span> <span class="s1">&#39;, &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">value</span><span class="p">)},</span> <span class="c1"># yaml: &#39;keywords&#39; list -&gt; str</span>
  642. <a name="rest_code_37ab99d321f34e6a81a1c6429c22ebcb-3"></a> <span class="s2">&quot;nikola&quot;</span><span class="p">:</span> <span class="p">{</span>
  643. <a name="rest_code_37ab99d321f34e6a81a1c6429c22ebcb-4"></a> <span class="s2">&quot;widgets&quot;</span><span class="p">:</span> <span class="k">lambda</span> <span class="n">value</span><span class="p">:</span> <span class="n">value</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">&#39;, &#39;</span><span class="p">),</span> <span class="c1"># nikola: &#39;widgets&#39; comma-separated string -&gt; list</span>
  644. <a name="rest_code_37ab99d321f34e6a81a1c6429c22ebcb-5"></a> <span class="s2">&quot;tags&quot;</span><span class="p">:</span> <span class="nb">str</span><span class="o">.</span><span class="n">lower</span> <span class="c1"># nikola: force lowercase &#39;tags&#39; (input would be string)</span>
  645. <a name="rest_code_37ab99d321f34e6a81a1c6429c22ebcb-6"></a> <span class="p">}</span>
  646. <a name="rest_code_37ab99d321f34e6a81a1c6429c22ebcb-7"></a><span class="p">}</span>
  647. </pre></section>
  648. </section>
  649. <section id="multilingual-posts">
  650. <h2><a class="toc-backref" href="#toc-entry-21" role="doc-backlink">Multilingual posts</a></h2>
  651. <p>If you are writing a multilingual site, you can also create a per-language
  652. post file (for example: <code class="docutils literal"><span class="pre">how-to-make-money.es.txt</span></code> with the default TRANSLATIONS_PATTERN, see below).
  653. This one can replace metadata of the default language, for example:</p>
  654. <ul class="simple">
  655. <li><p>The translated title for the post or page</p></li>
  656. <li><p>A translated version of the page name</p></li>
  657. </ul>
  658. <p>The pattern used for finding translations is controlled by the
  659. TRANSLATIONS_PATTERN variable in your configuration file.</p>
  660. <p>The default is to put the language code before the file extension,
  661. so the German translation of <code class="docutils literal">some_file.rst</code> should be named
  662. <code class="docutils literal">some_file.de.rst</code>. This is because the TRANSLATIONS_PATTERN variable is by
  663. default set to:</p>
  664. <pre class="code python"><a name="rest_code_9628a225d3d54553b5c855dc79ca360f-1"></a><span class="n">TRANSLATIONS_PATTERN</span> <span class="o">=</span> <span class="s2">&quot;</span><span class="si">{path}</span><span class="s2">.</span><span class="si">{lang}</span><span class="s2">.</span><span class="si">{ext}</span><span class="s2">&quot;</span>
  665. </pre><aside class="admonition admonition-considered-languages">
  666. <p class="admonition-title">Considered languages</p>
  667. <p>Nikola will only look for translation of input files for languages
  668. specified in the TRANSLATIONS variable.</p>
  669. </aside>
  670. <p>In case you translate your posts, you might also want to adjust various
  671. other settings so that the generated URLs match the translation. You can
  672. find most places in <code class="docutils literal">conf.py</code> by searching for <code class="docutils literal">(translatable)</code>. For example,
  673. you might want to localize <code class="docutils literal">/categories/</code> (search for <code class="docutils literal">TAG_PATH</code>), <code class="docutils literal">/pages/</code>
  674. and <code class="docutils literal">/posts/</code> (search for <code class="docutils literal">POSTS</code> and <code class="docutils literal">PAGES</code>, or see the next section), or
  675. how to adjust the URLs for subsequent pages for indexes (search for
  676. <code class="docutils literal">INDEXES_PRETTY_PAGE_URL</code>).</p>
  677. <p>Nikola supports multiple languages for a post (we have almost 50 translations!). If you wish to
  678. add support for more languages, check out <a class="reference external" href="https://www.transifex.com/projects/p/nikola/">the Transifex page for Nikola</a>.</p>
  679. </section>
  680. <section id="how-does-nikola-decide-where-posts-should-go">
  681. <h2><a class="toc-backref" href="#toc-entry-22" role="doc-backlink">How does Nikola decide where posts should go?</a></h2>
  682. <p>The place where the post will be placed by <code class="docutils literal">new_post</code> (the first one that
  683. matches the given format) and the final post destination (the first one that
  684. matches a given file) is based on the <code class="docutils literal">POSTS</code> and <code class="docutils literal">PAGES</code> configuration
  685. options. The exact mechanism is explained above the config options in the
  686. <code class="docutils literal">conf.py</code> file, and also reproduced below:</p>
  687. <pre class="code python"><a name="rest_code_6843e34d56cb46c7baae4db401bbab10-1"></a><span class="c1"># POSTS and PAGES contains (wildcard, destination, template) tuples.</span>
  688. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-2"></a><span class="c1">#</span>
  689. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-3"></a><span class="c1"># The wildcard is used to generate a list of post source files</span>
  690. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-4"></a><span class="c1"># (whatever/thing.rst, for example).</span>
  691. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-5"></a><span class="c1">#</span>
  692. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-6"></a><span class="c1"># That fragment could have an associated metadata file (whatever/thing.meta),</span>
  693. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-7"></a><span class="c1"># and optionally translated files (example for Spanish, with code &quot;es&quot;):</span>
  694. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-8"></a><span class="c1"># whatever/thing.es.rst and whatever/thing.es.meta</span>
  695. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-9"></a><span class="c1">#</span>
  696. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-10"></a><span class="c1"># This assumes you use the default TRANSLATIONS_PATTERN.</span>
  697. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-11"></a><span class="c1">#</span>
  698. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-12"></a><span class="c1"># From those files, a set of HTML fragment files will be generated:</span>
  699. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-13"></a><span class="c1"># cache/whatever/thing.html (and maybe cache/whatever/thing.html.es)</span>
  700. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-14"></a><span class="c1">#</span>
  701. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-15"></a><span class="c1"># These files are combined with the template to produce rendered</span>
  702. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-16"></a><span class="c1"># pages, which will be placed at</span>
  703. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-17"></a><span class="c1"># output/TRANSLATIONS[lang]/destination/pagename.html</span>
  704. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-18"></a><span class="c1">#</span>
  705. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-19"></a><span class="c1"># where &quot;pagename&quot; is the &quot;slug&quot; specified in the metadata file.</span>
  706. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-20"></a><span class="c1"># The page might also be placed in /destination/pagename/index.html</span>
  707. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-21"></a><span class="c1"># if PRETTY_URLS are enabled.</span>
  708. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-22"></a><span class="c1">#</span>
  709. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-23"></a><span class="c1"># The difference between POSTS and PAGES is that POSTS are added</span>
  710. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-24"></a><span class="c1"># to feeds, indexes, tag lists and archives and are considered part</span>
  711. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-25"></a><span class="c1"># of a blog, while PAGES are just independent HTML pages.</span>
  712. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-26"></a><span class="c1">#</span>
  713. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-27"></a><span class="c1"># Finally, note that destination can be translated, i.e. you can</span>
  714. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-28"></a><span class="c1"># specify a different translation folder per language. Example:</span>
  715. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-29"></a><span class="c1"># PAGES = (</span>
  716. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-30"></a><span class="c1"># (&quot;pages/*.rst&quot;, {&quot;en&quot;: &quot;pages&quot;, &quot;de&quot;: &quot;seiten&quot;}, &quot;page.tmpl&quot;),</span>
  717. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-31"></a><span class="c1"># (&quot;pages/*.md&quot;, {&quot;en&quot;: &quot;pages&quot;, &quot;de&quot;: &quot;seiten&quot;}, &quot;page.tmpl&quot;),</span>
  718. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-32"></a><span class="c1"># )</span>
  719. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-33"></a>
  720. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-34"></a><span class="n">POSTS</span> <span class="o">=</span> <span class="p">(</span>
  721. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-35"></a> <span class="p">(</span><span class="s2">&quot;posts/*.rst&quot;</span><span class="p">,</span> <span class="s2">&quot;posts&quot;</span><span class="p">,</span> <span class="s2">&quot;post.tmpl&quot;</span><span class="p">),</span>
  722. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-36"></a> <span class="p">(</span><span class="s2">&quot;posts/*.txt&quot;</span><span class="p">,</span> <span class="s2">&quot;posts&quot;</span><span class="p">,</span> <span class="s2">&quot;post.tmpl&quot;</span><span class="p">),</span>
  723. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-37"></a> <span class="p">(</span><span class="s2">&quot;posts/*.html&quot;</span><span class="p">,</span> <span class="s2">&quot;posts&quot;</span><span class="p">,</span> <span class="s2">&quot;post.tmpl&quot;</span><span class="p">),</span>
  724. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-38"></a><span class="p">)</span>
  725. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-39"></a><span class="n">PAGES</span> <span class="o">=</span> <span class="p">(</span>
  726. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-40"></a> <span class="p">(</span><span class="s2">&quot;pages/*.rst&quot;</span><span class="p">,</span> <span class="s2">&quot;pages&quot;</span><span class="p">,</span> <span class="s2">&quot;page.tmpl&quot;</span><span class="p">),</span>
  727. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-41"></a> <span class="p">(</span><span class="s2">&quot;pages/*.txt&quot;</span><span class="p">,</span> <span class="s2">&quot;pages&quot;</span><span class="p">,</span> <span class="s2">&quot;page.tmpl&quot;</span><span class="p">),</span>
  728. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-42"></a> <span class="p">(</span><span class="s2">&quot;pages/*.html&quot;</span><span class="p">,</span> <span class="s2">&quot;pages&quot;</span><span class="p">,</span> <span class="s2">&quot;page.tmpl&quot;</span><span class="p">),</span>
  729. <a name="rest_code_6843e34d56cb46c7baae4db401bbab10-43"></a><span class="p">)</span>
  730. </pre><aside class="admonition admonition-posts-and-pages-are-not-flat">
  731. <p class="admonition-title">POSTS and PAGES are not flat!</p>
  732. <p>Even if the syntax may suggest you can't, you can create any directory structure you want
  733. inside <code class="docutils literal">posts/</code> or <code class="docutils literal">pages/</code> and it will be reflected in the output. For example,
  734. <code class="docutils literal">posts/foo/bar.txt</code> would produce <code class="docutils literal">output/posts/foo/bar.html</code>, assuming the slug is also <code class="docutils literal">bar</code>.</p>
  735. <p>If you have <code class="docutils literal">PRETTY_URLS</code> enabled, that would be <code class="docutils literal">output/posts/foo/bar/index.html</code>.</p>
  736. </aside>
  737. <aside class="admonition warning">
  738. <p class="admonition-title">Warning</p>
  739. <p>Removing the <code class="docutils literal">.rst</code> entries is not recommended. Some features (eg.
  740. shortcodes) may not work properly if you do that.</p>
  741. </aside>
  742. </section>
  743. <section id="the-new-post-command">
  744. <h2><a class="toc-backref" href="#toc-entry-23" role="doc-backlink">The <code class="docutils literal">new_post</code> command</a></h2>
  745. <p><code class="docutils literal">new_post</code> will use the <em>first</em> path in <code class="docutils literal">POSTS</code> (or <code class="docutils literal">PAGES</code> if <code class="docutils literal"><span class="pre">-p</span></code> is
  746. supplied) that ends with the extension of your desired markup format (as
  747. defined in <code class="docutils literal">COMPILERS</code> in <code class="docutils literal">conf.py</code>) as the directory that the new post will be
  748. written into. If no such entry can be found, the post won’t be created.</p>
  749. <p>The <code class="docutils literal">new_post</code> command supports some options:</p>
  750. <pre class="code text"><a name="rest_code_9782f0650e3444fd9faf1a32898ca329-1"></a>$ nikola help new_post
  751. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-2"></a>Purpose: create a new blog post or site page
  752. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-3"></a>Usage: nikola new_post [options] [path]
  753. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-4"></a>
  754. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-5"></a>Options:
  755. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-6"></a> -p, --page Create a page instead of a blog post. (see also: `nikola new_page`)
  756. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-7"></a> -t ARG, --title=ARG Title for the post.
  757. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-8"></a> -a ARG, --author=ARG Author of the post.
  758. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-9"></a> --tags=ARG Comma-separated tags for the post.
  759. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-10"></a> -1 Create the post with embedded metadata (single file format)
  760. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-11"></a> -2 Create the post with separate metadata (two file format)
  761. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-12"></a> -e Open the post (and meta file, if any) in $EDITOR after creation.
  762. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-13"></a> -f ARG, --format=ARG Markup format for the post (use --available-formats for list)
  763. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-14"></a> -F, --available-formats List all available input formats
  764. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-15"></a> -s Schedule the post based on recurrence rule
  765. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-16"></a> -i ARG, --import=ARG Import an existing file instead of creating a placeholder
  766. <a name="rest_code_9782f0650e3444fd9faf1a32898ca329-17"></a> -d, --date-path Create post with date path (eg. year/month/day, see NEW_POST_DATE_PATH_FORMAT in config)
  767. </pre><p>The optional <code class="docutils literal">path</code> parameter tells Nikola exactly where to put it instead of guessing from your config.
  768. So, if you do <code class="docutils literal">nikola new_post posts/random/foo.txt</code> you will have a post in that path, with
  769. &quot;foo&quot; as its slug. You can also provide a directory name, in which case Nikola
  770. will append the file name for you (generated from title).</p>
  771. <p>The <code class="docutils literal"><span class="pre">-d,</span> <span class="pre">--date-path</span></code> option automates creation of <code class="docutils literal">year/month/day</code> or
  772. similar directory structures. It can be enabled on a per-post basis, or you can
  773. use it for every post if you set <code class="docutils literal">NEW_POST_DATE_PATH = True</code> in conf.py.</p>
  774. <pre class="code python"><a name="rest_code_c080bce44b294cb3be1a350c765176a7-1"></a><span class="c1"># Use date-based path when creating posts?</span>
  775. <a name="rest_code_c080bce44b294cb3be1a350c765176a7-2"></a><span class="c1"># Can be enabled on a per-post basis with `nikola new_post -d`.</span>
  776. <a name="rest_code_c080bce44b294cb3be1a350c765176a7-3"></a><span class="c1"># NEW_POST_DATE_PATH = False</span>
  777. <a name="rest_code_c080bce44b294cb3be1a350c765176a7-4"></a>
  778. <a name="rest_code_c080bce44b294cb3be1a350c765176a7-5"></a><span class="c1"># What format to use when creating posts with date paths?</span>
  779. <a name="rest_code_c080bce44b294cb3be1a350c765176a7-6"></a><span class="c1"># Default is &#39;%Y/%m/%d&#39;, other possibilities include &#39;%Y&#39; or &#39;%Y/%m&#39;.</span>
  780. <a name="rest_code_c080bce44b294cb3be1a350c765176a7-7"></a><span class="c1"># NEW_POST_DATE_PATH_FORMAT = &#39;%Y/%m/%d&#39;</span>
  781. </pre></section>
  782. <section id="teasers">
  783. <h2><a class="toc-backref" href="#toc-entry-24" role="doc-backlink">Teasers</a></h2>
  784. <p>You may not want to show the complete content of your posts either on your
  785. index page or in RSS feeds, but to display instead only the beginning of them.</p>
  786. <p>If it's the case, you only need to add a &quot;magical comment&quot; <code class="docutils literal">TEASER_END</code> or
  787. <code class="docutils literal">END_TEASER</code> in your post.</p>
  788. <p>In reStructuredText:</p>
  789. <pre class="code restructuredtext"><a name="rest_code_796ffc3896b74430bde6bfbf2cbc40db-1"></a><span class="cp">.. TEASER_END</span>
  790. </pre><p>In Markdown (or basically, the resulting HTML of any format):</p>
  791. <pre class="code html"><a name="rest_code_788bd8bb39c1481f81629f603ec19247-1"></a><span class="c">&lt;!-- TEASER_END --&gt;</span>
  792. </pre><p>By default all your RSS feeds will be shortened (they'll contain only teasers)
  793. whereas your index page will still show complete posts. You can change
  794. this behavior with your <code class="docutils literal">conf.py</code>: <code class="docutils literal">INDEX_TEASERS</code> defines whether index
  795. page should display the whole contents or only teasers. <code class="docutils literal">FEED_TEASERS</code>
  796. works the same way for your Atom and RSS feeds.</p>
  797. <p>By default, teasers will include a &quot;read more&quot; link at the end. If you want to
  798. change that text, you can use a custom teaser:</p>
  799. <pre class="code restructuredtext"><a name="rest_code_02756d18a9d140a7810d348b18f65273-1"></a><span class="cp">.. TEASER_END: click to read the rest of the article</span>
  800. </pre><p>You can override the default value for <code class="docutils literal">TEASER_END</code> in <code class="docutils literal">conf.py</code> — for
  801. example, the following example will work for <code class="docutils literal">.. more</code>, and will be
  802. compatible with both WordPress and Nikola posts:</p>
  803. <pre class="code python"><a name="rest_code_4169f76ff18044958b6007a3e59afadc-1"></a><span class="kn">import</span> <span class="nn">re</span>
  804. <a name="rest_code_4169f76ff18044958b6007a3e59afadc-2"></a><span class="n">TEASER_REGEXP</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s1">&#39;&lt;!--\s*(more|TEASER_END|END_TEASER)(:(.+))?\s*--&gt;&#39;</span><span class="p">,</span> <span class="n">re</span><span class="o">.</span><span class="n">IGNORECASE</span><span class="p">)</span>
  805. </pre><p>Or you can completely customize the link using the <code class="docutils literal">READ_MORE_LINK</code> option.</p>
  806. <pre class="code python"><a name="rest_code_30a1f62bce1e4a7da467b6067de5e70f-1"></a><span class="c1"># A HTML fragment with the Read more... link.</span>
  807. <a name="rest_code_30a1f62bce1e4a7da467b6067de5e70f-2"></a><span class="c1"># The following tags exist and are replaced for you:</span>
  808. <a name="rest_code_30a1f62bce1e4a7da467b6067de5e70f-3"></a><span class="c1"># {link} A link to the full post page.</span>
  809. <a name="rest_code_30a1f62bce1e4a7da467b6067de5e70f-4"></a><span class="c1"># {read_more} The string “Read more” in the current language.</span>
  810. <a name="rest_code_30a1f62bce1e4a7da467b6067de5e70f-5"></a><span class="c1"># {{ A literal { (U+007B LEFT CURLY BRACKET)</span>
  811. <a name="rest_code_30a1f62bce1e4a7da467b6067de5e70f-6"></a><span class="c1"># }} A literal } (U+007D RIGHT CURLY BRACKET)</span>
  812. <a name="rest_code_30a1f62bce1e4a7da467b6067de5e70f-7"></a><span class="c1"># READ_MORE_LINK = &#39;&lt;p class=&quot;more&quot;&gt;&lt;a href=&quot;{link}&quot;&gt;{read_more}…&lt;/a&gt;&lt;/p&gt;&#39;</span>
  813. </pre></section>
  814. <section id="drafts">
  815. <h2><a class="toc-backref" href="#toc-entry-25" role="doc-backlink">Drafts</a></h2>
  816. <p>If you set the <code class="docutils literal">status</code> metadata field of a post to <code class="docutils literal">draft</code>, it will not be shown
  817. in indexes and feeds. It <em>will</em> be compiled, and if you deploy it it <em>will</em> be made
  818. available, so use with care. If you wish your drafts to be not available in your
  819. deployed site, you can set <code class="docutils literal">DEPLOY_DRAFTS = False</code> in your configuration. This will
  820. not work if you include <code class="docutils literal">nikola build</code> in your <code class="docutils literal">DEPLOY_COMMANDS</code>, as the
  821. option removes the draft posts before any <code class="docutils literal">DEPLOY_COMMANDS</code> are run.</p>
  822. <p>Also if a post has a date in the future, it will not be shown in indexes until
  823. you rebuild after that date. This behavior can be disabled by setting
  824. <code class="docutils literal">FUTURE_IS_NOW = True</code> in your configuration, which will make future posts be
  825. published immediately. Posts dated in the future are <em>not</em> deployed by default
  826. (when <code class="docutils literal">FUTURE_IS_NOW = False</code>). To make future posts available in the
  827. deployed site, you can set <code class="docutils literal">DEPLOY_FUTURE = True</code> in your configuration.
  828. Generally, you want FUTURE_IS_NOW and DEPLOY_FUTURE to be the same value.</p>
  829. </section>
  830. <section id="private-posts">
  831. <h2><a class="toc-backref" href="#toc-entry-26" role="doc-backlink">Private Posts</a></h2>
  832. <p>If you set the <code class="docutils literal">status</code> metadata field of a post to <code class="docutils literal">private</code>, it will not be shown
  833. in indexes and feeds. It <em>will</em> be compiled, and if you deploy it it <em>will</em> be made
  834. available, so it will not generate 404s for people who had linked to it.</p>
  835. </section>
  836. <section id="featured-posts">
  837. <h2><a class="toc-backref" href="#toc-entry-27" role="doc-backlink">Featured Posts</a></h2>
  838. <p>Some themes, <code class="docutils literal">bootblog4</code> in particular, support featured posts. To mark a
  839. post as featured, simply set the <code class="docutils literal">status</code> meta field to <code class="docutils literal">featured</code>. All
  840. featured posts are available in index templates in a <code class="docutils literal">featured</code>
  841. list, but only if this is the main blog index.</p>
  842. <p>For bootblog4, you can display up to three posts as featured: one can be shown
  843. in a large gray box (jumbotron), and two more can appear in small white
  844. cards. In order to enable this feature, you need to add <code class="docutils literal">THEME_CONFIG</code> to
  845. your configuration, and set it up properly:</p>
  846. <pre class="code python"><a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-1"></a><span class="n">THEME_CONFIG</span> <span class="o">=</span> <span class="p">{</span>
  847. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-2"></a> <span class="n">DEFAULT_LANG</span><span class="p">:</span> <span class="p">{</span>
  848. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-3"></a> <span class="c1"># Show the latest featured post in a large box, with the previewimage as its background.</span>
  849. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-4"></a> <span class="s1">&#39;featured_large&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
  850. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-5"></a> <span class="c1"># Show the first (remaining) two featured posts in small boxes.</span>
  851. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-6"></a> <span class="s1">&#39;featured_small&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
  852. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-7"></a> <span class="c1"># Show featured posts on mobile.</span>
  853. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-8"></a> <span class="s1">&#39;featured_on_mobile&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
  854. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-9"></a> <span class="c1"># Show image in `featured_large` on mobile.</span>
  855. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-10"></a> <span class="c1"># `featured_small` displays them only on desktop.</span>
  856. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-11"></a> <span class="s1">&#39;featured_large_image_on_mobile&#39;</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span>
  857. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-12"></a> <span class="c1"># Strip HTML from featured post text.</span>
  858. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-13"></a> <span class="s1">&#39;featured_strip_html&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
  859. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-14"></a> <span class="c1"># Contents of the sidebar, If empty, the sidebar is not displayed.</span>
  860. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-15"></a> <span class="s1">&#39;sidebar&#39;</span><span class="p">:</span> <span class="s1">&#39;&#39;</span>
  861. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-16"></a> <span class="p">}</span>
  862. <a name="rest_code_cb5881d52ac94a3d88003a9ac15b878b-17"></a><span class="p">}</span>
  863. </pre><p>You can pick betweeen (up to) 1, 2, or 3 featured posts. You can mix
  864. <code class="docutils literal">featured_large</code> and <code class="docutils literal">featured_small</code>, rest assured that Nikola will always
  865. display the latest posts no matter what setup you choose. If only one posts
  866. qualifies for the small cards, one card taking up all the width will appear.</p>
  867. <p>Both featured box formats display an image to the right. You can set it by changing the <code class="docutils literal">previewimage</code> meta value to the full path to the image (eg. <code class="docutils literal">.. previewimage: /images/featured1.png</code>). This works best with images in portrait orientation.</p>
  868. <p>Note that, due to space constraints, only the large box may show the image on
  869. mobile, below the text (this behavior can be disbled). Small boxes never
  870. display images on mobile. In particular: <code class="docutils literal">xs</code> and <code class="docutils literal">sm</code> display only the
  871. large image, and only if configured; <code class="docutils literal">md</code> displays only the large image,
  872. <code class="docutils literal">lg</code> displays all three images.</p>
  873. <p>The boxes display only the teaser. We recommend keeping it short so
  874. you don’t get an ugly scrollbar.</p>
  875. <p>Finally, here’s an example (you’ll need to imagine a scrollbar in the right box
  876. yourself):</p>
  877. <a class="reference external image-reference" href="https://getnikola.com/images/bootblog4-featured2x.png"><img alt="An example of how featured posts look in bootblog4." class="align-center" src="https://getnikola.com/images/bootblog4-featured2x.thumbnail.png" /></a>
  878. </section>
  879. <section id="queuing-posts">
  880. <h2><a class="toc-backref" href="#toc-entry-28" role="doc-backlink">Queuing Posts</a></h2>
  881. <p>Some blogs tend to have new posts based on a schedule (for example,
  882. every Mon, Wed, Fri) but the blog authors don't like to manually
  883. schedule their posts. You can schedule your blog posts based on a
  884. rule, by specifying a rule in the <code class="docutils literal">SCHEDULE_RULE</code> in your
  885. configuration. You can either post specific blog posts according to
  886. this schedule by using the <code class="docutils literal"><span class="pre">--schedule</span></code> flag on the <code class="docutils literal">new_post</code>
  887. command or post all new posts according to this schedule by setting
  888. <code class="docutils literal">SCHEDULE_ALL = True</code> in your configuration. (Note: This feature
  889. requires that the <code class="docutils literal">FUTURE_IS_NOW</code> setting is set to <code class="docutils literal">False</code>)</p>
  890. <p>For example, if you would like to schedule your posts to be on every
  891. Monday, Wednesday and Friday at 7am, add the following
  892. <code class="docutils literal">SCHEDULE_RULE</code> to your configuration:</p>
  893. <pre class="code python"><a name="rest_code_e199bcced54a4aad92c8faac51a1834a-1"></a><span class="n">SCHEDULE_RULE</span> <span class="o">=</span> <span class="s1">&#39;RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR;BYHOUR=7;BYMINUTE=0;BYSECOND=0&#39;</span>
  894. </pre><p>For more details on how to specify a recurrence rule, look at the
  895. <a class="reference external" href="https://www.kanzaki.com/docs/ical/rrule.html">iCal specification</a>.
  896. Or if you are scared of this format, many calendaring applications (eg. Google
  897. Calendar) offer iCal exports, so you can copy-paste the repeat rule from a
  898. generated iCal (<code class="docutils literal">.ics</code>) file (which is a human-readable text file).</p>
  899. <p>Say, you get a free Sunday, and want to write a flurry of new posts,
  900. or at least posts for the rest of the week, you would run the
  901. <code class="docutils literal">new_post</code> command with the <code class="docutils literal"><span class="pre">--schedule</span></code> flag, as many times as
  902. you want:</p>
  903. <pre class="code console"><a name="rest_code_6047b3534ea34d4aa3940809bb8419a5-1"></a><span class="gp">$</span> nikola new_post --schedule
  904. <a name="rest_code_6047b3534ea34d4aa3940809bb8419a5-2"></a><span class="gp">#</span> Creates a new post to be posted on Monday, 7am.
  905. <a name="rest_code_6047b3534ea34d4aa3940809bb8419a5-3"></a><span class="gp">$</span> nikola new_post -s
  906. <a name="rest_code_6047b3534ea34d4aa3940809bb8419a5-4"></a><span class="gp">#</span> Creates a new post to be posted on Wednesday, 7am.
  907. <a name="rest_code_6047b3534ea34d4aa3940809bb8419a5-5"></a><span class="gp">$</span> nikola new_post -s
  908. <a name="rest_code_6047b3534ea34d4aa3940809bb8419a5-6"></a><span class="gp">#</span> Creates a new post to be posted on Friday, 7am.
  909. <a name="rest_code_6047b3534ea34d4aa3940809bb8419a5-7"></a><span class="go">.</span>
  910. <a name="rest_code_6047b3534ea34d4aa3940809bb8419a5-8"></a><span class="go">.</span>
  911. <a name="rest_code_6047b3534ea34d4aa3940809bb8419a5-9"></a><span class="go">.</span>
  912. </pre><p>All these posts get queued up according to your schedule, but note
  913. that you will anyway need to build and deploy your site for the posts
  914. to appear online. You can have a cron job that does this regularly.</p>
  915. </section>
  916. <section id="post-types">
  917. <h2><a class="toc-backref" href="#toc-entry-29" role="doc-backlink">Post Types</a></h2>
  918. <p>Nikola supports specifying post types, just like Tumblr does. Post
  919. types affect the look of your posts, by adding a <code class="docutils literal"><span class="pre">post-YOURINPUTHERE</span></code>
  920. CSS class to the post. Each post can have one and exactly one type. Nikola
  921. styles the following types in the default themes:</p>
  922. <table class="table table-bordered">
  923. <thead>
  924. <tr><th class="head"><p>Name(s)</p></th>
  925. <th class="head"><p>Description</p></th>
  926. <th class="head"><p>Styling</p></th>
  927. </tr>
  928. </thead>
  929. <tbody>
  930. <tr><td><p>text</p></td>
  931. <td><p>plain text — default value</p></td>
  932. <td><p>standard</p></td>
  933. </tr>
  934. <tr><td><p>micro</p></td>
  935. <td><p>“small” (short) posts</p></td>
  936. <td><p>big serif font</p></td>
  937. </tr>
  938. </tbody>
  939. </table>
  940. </section>
  941. <section id="indexes">
  942. <h2><a class="toc-backref" href="#toc-entry-30" role="doc-backlink">Indexes</a></h2>
  943. <p>All your posts that are not drafts, private or dated in the future, will be
  944. shown in indexes.</p>
  945. <section id="settings">
  946. <h3><a class="toc-backref" href="#toc-entry-31" role="doc-backlink">Settings</a></h3>
  947. <p>Indexes are put in the <code class="docutils literal">INDEX_PATH</code> directory, which defaults to an empty
  948. string (site root). The “main” index is <code class="docutils literal">index.html</code>, and all the further
  949. indexes are <code class="docutils literal"><span class="pre">index-*.html</span></code>, respectively.</p>
  950. <p>By default, 10 posts are displayed on an index page. This can be changed with
  951. <code class="docutils literal">INDEX_DISPLAY_POST_COUNT</code>. Indexes can show full posts or just the teasers,
  952. as controlled by the <code class="docutils literal">INDEX_TEASERS</code> setting (defaults to <code class="docutils literal">False</code>).</p>
  953. <p>Titles of the pages can be controlled by using <code class="docutils literal">INDEXES_TITLES</code>,
  954. <code class="docutils literal">INDEXES_PAGES</code> and <code class="docutils literal">INDEXES_PAGES_MAIN</code> settings.</p>
  955. <p>Categories and tags use simple lists by default that show only titles and
  956. dates; however, you can switch them to full indexes by using
  957. <code class="docutils literal">CATEGORY_PAGES_ARE_INDEXES</code> and <code class="docutils literal">TAG_PAGES_ARE_INDEXES</code>, respectively.</p>
  958. <p>Something similar happens with authors. To use full indexes in authors, set
  959. <code class="docutils literal">AUTHOR_PAGES_ARE_INDEXES</code> to <code class="docutils literal">True</code>.</p>
  960. </section>
  961. <section id="static-indexes">
  962. <h3><a class="toc-backref" href="#toc-entry-32" role="doc-backlink">Static indexes</a></h3>
  963. <p>Nikola uses <em>static indexes</em> by default. This means that <code class="docutils literal"><span class="pre">index-1.html</span></code> has
  964. the oldest posts, and the newest posts past the first 10 are in
  965. <code class="docutils literal"><span class="pre">index-N.html</span></code>, where <code class="docutils literal">N</code> is the highest number. Only the page with the
  966. highest number and the main page (<code class="docutils literal"><span class="pre">index-N.html</span></code> and <code class="docutils literal">index.html</code>) are
  967. rebuilt (the others remain unchanged). The page that appears when you click
  968. <em>Older posts</em> on the index page, <code class="docutils literal"><span class="pre">index-N.html</span></code>, might contain <strong>less than 10
  969. posts</strong> if there are not enough posts to fill up all pages.</p>
  970. <p>This can be disabled by setting <code class="docutils literal">INDEXES_STATIC</code> to <code class="docutils literal">False</code>. In that mode,
  971. <code class="docutils literal"><span class="pre">index-1.html</span></code> contains all the newest posts past the first 10 and will
  972. always contain 10 posts (unless you have less than 20). The last page,
  973. <code class="docutils literal"><span class="pre">index-N.html</span></code>, contains the oldest posts, and might contain less than 10
  974. posts. This is how many blog engines and CMSes behave. Note that this will
  975. lead to rebuilding all index pages, which might be a problem for larger blogs
  976. (with a lot of index pages).</p>
  977. </section>
  978. </section>
  979. <section id="post-taxonomy">
  980. <h2><a class="toc-backref" href="#toc-entry-33" role="doc-backlink">Post taxonomy</a></h2>
  981. <p>There are two taxonomy systems in Nikola, or two ways to organize posts. Those are tags and categories. They are visible on the <em>Tags and Categories</em> page, by default available at <code class="docutils literal">/categories/</code>. Each tag/category has an index page and feeds.</p>
  982. <section id="tags">
  983. <h3><a class="toc-backref" href="#toc-entry-34" role="doc-backlink">Tags</a></h3>
  984. <p>Tags are the smallest and most basic of the taxonomy items. A post can have multiple tags, specified using the <code class="docutils literal">tags</code> metadata entry (comma-separated). You should provide many tags to help your readers, and perhaps search engines, find content on your site.</p>
  985. <p>Please note that tags are case-sensitive and that you cannot have two tags that differ only in case/punctuation (eg. using <code class="docutils literal">nikola</code> in one post and <code class="docutils literal">Nikola</code> in another will lead to a crash):</p>
  986. <pre class="code text"><a name="rest_code_1fd858ac735b4e729c0d0c4ca1acda15-1"></a>ERROR: Nikola: You have tags that are too similar: Nikola and nikola
  987. <a name="rest_code_1fd858ac735b4e729c0d0c4ca1acda15-2"></a>ERROR: Nikola: Tag Nikola is used in: posts/second-post.rst
  988. <a name="rest_code_1fd858ac735b4e729c0d0c4ca1acda15-3"></a>ERROR: Nikola: Tag nikola is used in: posts/1.rst
  989. </pre><p>You can also generate a tag cloud with the <a class="reference external" href="https://plugins.getnikola.com/v7/tx3_tag_cloud/">tx3_tag_cloud</a> plugin or get a data file for a tag cloud with the <a class="reference external" href="https://plugins.getnikola.com/v8/tagcloud/">tagcloud</a> plugin.</p>
  990. </section>
  991. <section id="categories">
  992. <h3><a class="toc-backref" href="#toc-entry-35" role="doc-backlink">Categories</a></h3>
  993. <p>The next unit for organizing your content are categories. A post can have only one category, specified with the <code class="docutils literal">category</code> meta tag. They are displayed alongside tags. You can have categories and tags with the same name (categories’ RSS and HTML files are prefixed with <code class="docutils literal">cat_</code> by default).</p>
  994. <p>Categories are handy to organize different parts of your blog, parts that are about different topics. Unlike tags, which you should have tens (hundreds?) of, the list of categories should be shorter.</p>
  995. <p>Nikola v7 used to support a third taxonomy, called sections. Those have been removed, but all the functionality can be recreated by using the <code class="docutils literal">CATEGORY_DESTPATH</code> settings.</p>
  996. </section>
  997. <section id="configuring-tags-and-categories">
  998. <h3><a class="toc-backref" href="#toc-entry-36" role="doc-backlink">Configuring tags and categories</a></h3>
  999. <p>There are multiple configuration variables dedicated to each of the two taxonomies. You can set:</p>
  1000. <ul class="simple">
  1001. <li><p><code class="docutils literal">TAG_PATH</code>, <code class="docutils literal">TAGS_INDEX_PATH</code>, <code class="docutils literal">CATEGORY_PATH</code>, <code class="docutils literal">CATEGORY_PREFIX</code> to configure paths used for tags and categories</p></li>
  1002. <li><p><code class="docutils literal">TAG_TITLES</code>, <code class="docutils literal">CATEGORY_TITLES</code> to set titles and descriptions for index pages</p></li>
  1003. <li><p><code class="docutils literal">TAG_DESCRIPTIONS</code>, <code class="docutils literal">CATEGORY_DESCRIPTIONS</code> to set descriptions for each of the items</p></li>
  1004. <li><p><code class="docutils literal">CATEGORY_ALLOW_HIERARCHIES</code> and <code class="docutils literal">CATEGORY_OUTPUT_FLAT_HIERARCHIES</code> to allow hierarchical categories</p></li>
  1005. <li><p><code class="docutils literal">TAG_PAGES_ARE_INDEXES</code> and <code class="docutils literal">CATEGORY_PAGES_ARE_INDEXES</code> to display full-size indexes instead of simple post lists</p></li>
  1006. <li><p><code class="docutils literal">HIDDEN_TAGS</code>. <code class="docutils literal">HIDDEN_CATEGORIES</code> to make some tags/categories invisible in lists</p></li>
  1007. <li><p><code class="docutils literal">CATEGORY_DESTPATH_AS_DEFAULT</code> to use the destination path as the category if none is specified in the post</p></li>
  1008. <li><p><code class="docutils literal">CATEGORY_DESTPATH_TRIM_PREFIX</code> to trim the prefix that comes from <code class="docutils literal">POSTS</code> for the destination path</p></li>
  1009. <li><p><code class="docutils literal">CATEGORY_DESTPATH_FIRST_DIRECTORY</code> to only use the first directory name for the defaulted category</p></li>
  1010. <li><p><code class="docutils literal">CATEGORY_DESTPATH_NAMES</code> to specify friendly names for defaulted categories</p></li>
  1011. <li><p><code class="docutils literal">CATEGORY_PAGES_FOLLOW_DESTPATH</code> to put category pages next to their related posts (via destpath)</p></li>
  1012. </ul>
  1013. </section>
  1014. </section>
  1015. <section id="what-if-i-dont-want-a-blog">
  1016. <h2><a class="toc-backref" href="#toc-entry-37" role="doc-backlink">What if I don’t want a blog?</a></h2>
  1017. <p>If you want a static site that does not have any blog-related elements, see our
  1018. <a class="reference external" href="https://getnikola.com/creating-a-site-not-a-blog-with-nikola.html">Creating a Site (Not a Blog) with Nikola</a> guide.</p>
  1019. </section>
  1020. </section>
  1021. <section id="creating-a-page">
  1022. <h1><a class="toc-backref" href="#toc-entry-38" role="doc-backlink">Creating a Page</a></h1>
  1023. <p>Pages are the same as posts, except that:</p>
  1024. <ul class="simple">
  1025. <li><p>They are not added to the front page</p></li>
  1026. <li><p>They don't appear on the RSS feed</p></li>
  1027. <li><p>They use the <code class="docutils literal">page.tmpl</code> template instead of <code class="docutils literal">post.tmpl</code> by default</p></li>
  1028. </ul>
  1029. <p>The default configuration expects the page's metadata and text files to be on the
  1030. <code class="docutils literal">pages</code> folder, but that can be changed (see <code class="docutils literal">PAGES</code> option above).</p>
  1031. <p>You can create the page's files manually or use the <code class="docutils literal">new_post</code> command
  1032. with the <code class="docutils literal"><span class="pre">-p</span></code> option, which will place the files in the folder that
  1033. has <code class="docutils literal">use_in_feed</code> set to False.</p>
  1034. <p>In some places (including default directories and templates), pages are called
  1035. <em>stories</em> for historic reasons. Both are synonyms for the same thing: pages
  1036. that are not blog posts.</p>
  1037. </section>
  1038. <section id="supported-input-formats">
  1039. <h1><a class="toc-backref" href="#toc-entry-39" role="doc-backlink">Supported input formats</a></h1>
  1040. <p>Nikola supports multiple input formats. Out of the box, we have compilers available for:</p>
  1041. <ul class="simple">
  1042. <li><p>reStructuredText (default and pre-configured)</p></li>
  1043. <li><p><a class="reference internal" href="#markdown">Markdown</a> (pre-configured since v7.8.7)</p></li>
  1044. <li><p><a class="reference internal" href="#jupyter-notebook">Jupyter Notebook</a></p></li>
  1045. <li><p><a class="reference internal" href="#html">HTML</a></p></li>
  1046. <li><p><a class="reference internal" href="#php">PHP</a></p></li>
  1047. <li><p>anything <a class="reference internal" href="#pandoc">Pandoc</a> supports (including Textile, DocBook, LaTeX, MediaWiki,
  1048. TWiki, OPML, Emacs Org-Mode, txt2tags, Microsoft Word .docx, EPUB, Haddock markup)</p></li>
  1049. </ul>
  1050. <p>Plus, we have specialized compilers in the Plugins Index for:</p>
  1051. <ul class="simple">
  1052. <li><p><a class="reference external" href="https://plugins.getnikola.com/#asciidoc">AsciiDoc</a></p></li>
  1053. <li><p><a class="reference external" href="https://plugins.getnikola.com/#bbcode">BBCode</a></p></li>
  1054. <li><p><a class="reference external" href="https://plugins.getnikola.com/#commonmark">CommonMark</a></p></li>
  1055. <li><p><a class="reference external" href="https://plugins.getnikola.com/#irclogs">IRC logs</a></p></li>
  1056. <li><p><a class="reference external" href="https://plugins.getnikola.com/#markmin">Markmin</a></p></li>
  1057. <li><p><a class="reference external" href="https://plugins.getnikola.com/#mediawiki">MediaWiki (smc.mw)</a></p></li>
  1058. <li><p><a class="reference external" href="https://plugins.getnikola.com/#misaka">Misaka</a></p></li>
  1059. <li><p><a class="reference external" href="https://plugins.getnikola.com/#odt">ODT</a></p></li>
  1060. <li><p><a class="reference external" href="https://plugins.getnikola.com/#orgmode">Emacs Org-Mode</a></p></li>
  1061. <li><p><a class="reference external" href="https://plugins.getnikola.com/#rest_html5">reST with HTML 5 output</a></p></li>
  1062. <li><p><a class="reference external" href="https://plugins.getnikola.com/#textile">Textile</a></p></li>
  1063. <li><p><a class="reference external" href="https://plugins.getnikola.com/#txt2tags">txt2tags</a></p></li>
  1064. <li><p><a class="reference external" href="https://plugins.getnikola.com/#wiki">CreoleWiki</a></p></li>
  1065. <li><p><a class="reference external" href="https://plugins.getnikola.com/#wordpress_compiler">WordPress posts</a></p></li>
  1066. </ul>
  1067. <p>To write posts in a different format, you need to configure the compiler and
  1068. paths. To create a post, use <code class="docutils literal">nikola new_post <span class="pre">-f</span> COMPILER_NAME</code>, eg. <code class="docutils literal">nikola
  1069. new_post <span class="pre">-f</span> markdown</code>. The default compiler used is the first entry in POSTS
  1070. or PAGES.</p>
  1071. <section id="configuring-other-input-formats">
  1072. <h2><a class="toc-backref" href="#toc-entry-40" role="doc-backlink">Configuring other input formats</a></h2>
  1073. <p>In order to use input formats other than reStructuredText, you need some extra
  1074. setup.</p>
  1075. <ol class="arabic simple">
  1076. <li><p>Make sure you have the compiler for the input format you want. Some
  1077. input formats are supported out-of-the-box, but others must be installed from
  1078. the Plugins repository. You may also need some extra dependencies. You
  1079. will get helpful errors if you try to build when missing something.</p></li>
  1080. <li><p>You must ensure the compiler and your desired input file extension is included
  1081. in the <code class="docutils literal">COMPILERS</code> dict and does not conflict with any other format. This
  1082. is extremely important for the pandoc compiler.</p></li>
  1083. <li><p>Finally, you must configure the <code class="docutils literal">POSTS</code> and <code class="docutils literal">PAGES</code> tuples. Follow the
  1084. instructions and the format set by pre-existing entries. Make sure to use
  1085. the same extension as is set in <code class="docutils literal">COMPILERS</code> and configure the outputs
  1086. properly.</p></li>
  1087. </ol>
  1088. <section id="markdown">
  1089. <h3><a class="toc-backref" href="#toc-entry-41" role="doc-backlink">Markdown</a></h3>
  1090. <p>To use Markdown in your posts/pages, make sure <code class="docutils literal">markdown</code> is in your
  1091. <code class="docutils literal">COMPILERS</code> and that at least one of your desired extensions is defined in
  1092. <code class="docutils literal">POSTS</code> and <code class="docutils literal">PAGES</code>.</p>
  1093. <p>You can use Python-Markdown extensions by setting the <code class="docutils literal">MARKDOWN_EXTENSIONS</code>
  1094. config option:</p>
  1095. <pre class="code python"><a name="rest_code_a46ae67e54354434b5022a9db95d2952-1"></a><span class="n">MARKDOWN_EXTENSIONS</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;fenced_code&#39;</span><span class="p">,</span> <span class="s1">&#39;codehilite&#39;</span><span class="p">,</span> <span class="s1">&#39;extra&#39;</span><span class="p">]</span>
  1096. </pre><p>Nikola comes with some Markdown Extensions built-in and enabled by default,
  1097. namely a gist directive, a podcast directive, and <code class="docutils literal">~~strikethrough~~</code> support.</p>
  1098. </section>
  1099. <section id="jupyter-notebook">
  1100. <h3><a class="toc-backref" href="#toc-entry-42" role="doc-backlink">Jupyter Notebook</a></h3>
  1101. <p>To use Jupyter Notebooks as posts/pages, make sure <code class="docutils literal">ipynb</code> is in your
  1102. <code class="docutils literal">COMPILERS</code> and that the <code class="docutils literal">.ipynb</code> extension is defined in <code class="docutils literal">POSTS</code> and
  1103. <code class="docutils literal">PAGES</code>.</p>
  1104. <p>The <code class="docutils literal"><span class="pre">-f</span></code> argument to <code class="docutils literal">new_post</code> should be used in the <code class="docutils literal">ipynb&#64;KERNEL</code> format.
  1105. It defaults to Python in the version used by Nikola if not specified.</p>
  1106. <p>Jupyter Notebooks are also supported in stand-alone listings, if Jupyter
  1107. support is enabled site-wide. You must have something for <code class="docutils literal">.ipynb</code> in POSTS
  1108. or PAGES for the feature to work.</p>
  1109. </section>
  1110. <section id="html">
  1111. <h3><a class="toc-backref" href="#toc-entry-43" role="doc-backlink">HTML</a></h3>
  1112. <p>To use plain HTML in your posts/pages, make sure <code class="docutils literal">html</code> is in your
  1113. <code class="docutils literal">COMPILERS</code>
  1114. and that the <code class="docutils literal">.html</code> extension is defined in <code class="docutils literal">POSTS</code> and <code class="docutils literal">PAGES</code>.</p>
  1115. </section>
  1116. <section id="php">
  1117. <h3><a class="toc-backref" href="#toc-entry-44" role="doc-backlink">PHP</a></h3>
  1118. <p>There are two ways of using PHP within Nikola:</p>
  1119. <ol class="arabic simple">
  1120. <li><p>To use PHP in your posts/pages (inside your site, with the theme and
  1121. everything), make sure <code class="docutils literal">php</code> is in your <code class="docutils literal">COMPILERS</code> and that the <code class="docutils literal">.php</code>
  1122. extension is defined in <code class="docutils literal">POSTS</code> and <code class="docutils literal">PAGES</code>.</p></li>
  1123. <li><p>To use PHP as standalone files (without any modifications), put them in
  1124. <code class="docutils literal">files/</code> (or whatever <code class="docutils literal">FILES_FOLDERS</code> is configured to).</p></li>
  1125. </ol>
  1126. </section>
  1127. <section id="pandoc">
  1128. <h3><a class="toc-backref" href="#toc-entry-45" role="doc-backlink">Pandoc</a></h3>
  1129. <p>To use Pandoc, you must uncomment the entry in <code class="docutils literal">COMPILERS</code> and set the
  1130. extensions list to your desired extensions while also removing them from their
  1131. original compilers. The input format is inferred from the extension by Pandoc.</p>
  1132. <p>Using Pandoc for reStructuredText, Markdown and other input formats that have a
  1133. standalone Nikola plugin is <strong>not recommended</strong> as it disables plugins and
  1134. extensions that are usually provided by Nikola.</p>
  1135. </section>
  1136. </section>
  1137. </section>
  1138. <section id="shortcodes">
  1139. <h1><a class="toc-backref" href="#toc-entry-46" role="doc-backlink">Shortcodes</a></h1>
  1140. <p>This feature is &quot;inspired&quot; (copied wholesale) from <a class="reference external" href="https://gohugo.io/extras/shortcodes/">Hugo</a> so I will
  1141. steal part of their docs too.</p>
  1142. <p>A shortcode is a simple snippet inside a content file that Nikola will render using a predefined template or
  1143. custom code from a plugin.</p>
  1144. <p>To use them from plugins, please see <a class="reference external" href="https://getnikola.com/extending.html#shortcodes">Extending Nikola</a></p>
  1145. <section id="using-a-shortcode">
  1146. <h2><a class="toc-backref" href="#toc-entry-47" role="doc-backlink">Using a shortcode</a></h2>
  1147. <p>In your content files, a shortcode can be called by using this form:</p>
  1148. <pre class="code text"><a name="rest_code_6b7397d9da374a2d89ab31d8b45b330f-1"></a>{{% name parameters %}}
  1149. </pre><p>Shortcode parameters are space delimited. Parameters with spaces can be quoted (or backslash escaped).</p>
  1150. <p>The first word is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional or both. The format for named parameters models that of HTML with the format name=&quot;value&quot;.</p>
  1151. <p>Some shortcodes use or require closing shortcodes. Like HTML, the opening and closing shortcodes match (name only), the closing being prepended with a slash.</p>
  1152. <p>Example of a paired shortcode (note that we don't have a highlight shortcode yet ;-):</p>
  1153. <pre class="code text"><a name="rest_code_1e131e5fc6034757a15f5771dcf2b942-1"></a>{{% highlight python %}} A bunch of code here {{% /highlight %}}
  1154. </pre><aside class="admonition admonition-shortcodes-and-restructuredtext">
  1155. <p class="admonition-title">Shortcodes and reStructuredText</p>
  1156. <p>In reStructuredText shortcodes may fail because docutils turns URL into links and everything breaks.
  1157. For some shortcodes there are alternative docutils directives (example, you can use the media
  1158. <strong>directive</strong> instead of the media shortcode.</p>
  1159. <p>Also, you can use the shortcode <strong>role</strong>:</p>
  1160. <pre class="code text"><a name="rest_code_0cacd5f7c1074a69b8a05093efbf003a-1"></a>:sc:`{{% shortcode here %}}`
  1161. </pre><p>That role passes text unaltered, so shortcodes behave correctly.</p>
  1162. </aside>
  1163. </section>
  1164. <section id="built-in-shortcodes">
  1165. <h2><a class="toc-backref" href="#toc-entry-48" role="doc-backlink">Built-in shortcodes</a></h2>
  1166. <aside class="admonition warning">
  1167. <p class="admonition-title">Warning</p>
  1168. <p>Some of the shortcodes are implemented as bindings to reST directives. In
  1169. order to use them, you need at least one entry for <code class="docutils literal">*.rst</code> in
  1170. POSTS/PAGES.</p>
  1171. </aside>
  1172. <dl>
  1173. <dt>chart</dt>
  1174. <dd><p>Create charts via PyGal. This is similar to the <a class="reference external" href="#chart">chart directive</a> except the syntax is adapted to
  1175. shortcodes. This is an example:</p>
  1176. <pre class="code text"><a name="rest_code_9d84fdc1b4ed46b492a2126e3a2c60fc-1"></a>{{% chart Bar title='Browser usage evolution (in %)'
  1177. x_labels='["2002","2003","2004","2005","2006","2007"]' %}}
  1178. 'Firefox', [None, None, 0, 16.6, 25, 31]
  1179. 'Chrome', [None, None, None, None, None, None]
  1180. 'IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6]
  1181. 'Others', [14.2, 15.4, 15.3, 8.9, 9, 10.4]
  1182. {{% /chart %}}
  1183. </pre><p>Additionally, you can use a file_data argument which can point to a JSON or YAML file, and will be used for both arguments and data.
  1184. Example:</p>
  1185. <pre class="code json"><a name="rest_code_ff04f4c00c014e4b944ab66d85f8b3f1-1"></a><span class="p">{</span>
  1186. <a name="rest_code_ff04f4c00c014e4b944ab66d85f8b3f1-2"></a> <span class="nt">&quot;x_labels&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;2002&quot;</span><span class="p">,</span><span class="s2">&quot;2003&quot;</span><span class="p">,</span><span class="s2">&quot;2004&quot;</span><span class="p">,</span><span class="s2">&quot;2005&quot;</span><span class="p">,</span><span class="s2">&quot;2006&quot;</span><span class="p">,</span><span class="s2">&quot;2007&quot;</span><span class="p">],</span>
  1187. <a name="rest_code_ff04f4c00c014e4b944ab66d85f8b3f1-3"></a> <span class="nt">&quot;data&quot;</span><span class="p">:</span> <span class="p">{</span>
  1188. <a name="rest_code_ff04f4c00c014e4b944ab66d85f8b3f1-4"></a> <span class="nt">&quot;Firefox&quot;</span><span class="p">:</span> <span class="p">[</span><span class="kc">null</span><span class="p">,</span> <span class="kc">null</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">16.6</span><span class="p">,</span> <span class="mi">25</span><span class="p">,</span> <span class="mi">31</span><span class="p">],</span>
  1189. <a name="rest_code_ff04f4c00c014e4b944ab66d85f8b3f1-5"></a> <span class="nt">&quot;Chrome&quot;</span><span class="p">:</span> <span class="p">[</span><span class="kc">null</span><span class="p">,</span> <span class="kc">null</span><span class="p">,</span> <span class="kc">null</span><span class="p">,</span> <span class="kc">null</span><span class="p">,</span> <span class="kc">null</span><span class="p">,</span> <span class="kc">null</span><span class="p">],</span>
  1190. <a name="rest_code_ff04f4c00c014e4b944ab66d85f8b3f1-6"></a> <span class="nt">&quot;IE&quot;</span><span class="p">:</span> <span class="p">[</span><span class="mf">85.8</span><span class="p">,</span> <span class="mf">84.6</span><span class="p">,</span> <span class="mf">84.7</span><span class="p">,</span> <span class="mf">74.5</span><span class="p">,</span> <span class="mi">66</span><span class="p">,</span> <span class="mf">58.6</span><span class="p">],</span>
  1191. <a name="rest_code_ff04f4c00c014e4b944ab66d85f8b3f1-7"></a> <span class="nt">&quot;Others&quot;</span><span class="p">:</span> <span class="p">[</span><span class="mf">14.2</span><span class="p">,</span> <span class="mf">15.4</span><span class="p">,</span> <span class="mf">15.3</span><span class="p">,</span> <span class="mf">8.9</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mf">10.4</span><span class="p">]</span>
  1192. <a name="rest_code_ff04f4c00c014e4b944ab66d85f8b3f1-8"></a> <span class="p">}</span>
  1193. <a name="rest_code_ff04f4c00c014e4b944ab66d85f8b3f1-9"></a><span class="p">}</span>
  1194. </pre><p>Which can be used like this:</p>
  1195. <pre class="code text"><a name="rest_code_3e93e8d1415445c19b810e7762374be9-1"></a>{{% chart Bar title='Browser usage evolution (in %)' data_file="posts/browsers.json" %}}
  1196. {{% /chart %}}
  1197. </pre><p>If the data or any option is available in both the <code class="docutils literal">data_file</code> and the document, the document has priority.</p>
  1198. </dd>
  1199. <dt>doc</dt>
  1200. <dd><p>Will link to a document in the page, see <a class="reference external" href="#doc">Doc role for details</a>. Example:</p>
  1201. <pre class="code restructuredtext"><a name="rest_code_9a52aaf6ba0c4feb8197767861859270-1"></a>Take a look at {{% doc %}}my other post <creating-a-theme>{{% /doc %}} about theme creating.
  1202. </pre></dd>
  1203. <dt>emoji</dt>
  1204. <dd><p>Insert an emoji. For example:</p>
  1205. <pre class="code text"><a name="rest_code_e4464a529059439cbf1348acd5c66852-1"></a>{{% emoji crying_face %}}
  1206. </pre><p>This generates a <code class="docutils literal">span</code> with <code class="docutils literal">emoji</code> CSS class, so you can style it with a nice font if you want.</p>
  1207. </dd>
  1208. <dt>gist</dt>
  1209. <dd><p>Show GitHub gists. If you know the gist's ID, this will show it in your site:</p>
  1210. <pre class="code text"><a name="rest_code_ee980f0114414247915df0035769e2e6-1"></a>{{% gist 2395294 %}}
  1211. </pre></dd>
  1212. <dt>listing</dt>
  1213. <dd><p>Used to show a code listing. Example:</p>
  1214. <pre class="code text"><a name="rest_code_2969e45f45a44461bd525578ddd28a35-1"></a>{{% listing hello.py python linenumbers=True %}}
  1215. </pre><p>It takes a file name or path, an optional language to highlight, and a linenumbers option to enable/disable line numbers in the output.</p>
  1216. </dd>
  1217. <dt>media</dt>
  1218. <dd><p>Display media embedded from a URL, for example, this will embed a youtube video:</p>
  1219. <pre class="code text"><a name="rest_code_5b57f4c40c5a446da8740b141360f2ca-1"></a>{{% media url=https://www.youtube.com/watch?v=Nck6BZga7TQ %}}
  1220. </pre><p>Note that the shortcode won’t work if your compiler turns URLs into clickable links.</p>
  1221. </dd>
  1222. <dt>post-list</dt>
  1223. <dd><p>Will show a list of posts, see the <a class="reference external" href="#post-list">Post List directive for details</a>.</p>
  1224. </dd>
  1225. <dt>raw</dt>
  1226. <dd><p>Passes the content along, mostly used so I can write this damn section and you can see the shortcodes instead
  1227. of them being munged into shortcode <strong>output</strong>. I can't show an example because Inception.</p>
  1228. </dd>
  1229. <dt>thumbnail</dt>
  1230. <dd><p>Display image thumbnails, with optional captions. Examples:</p>
  1231. <pre class="code text"><a name="rest_code_1361b6c7517446d598a599277dcd9727-1"></a>{{% thumbnail "/images/foo.png" %}}{{% /thumbnail %}}
  1232. <a name="rest_code_1361b6c7517446d598a599277dcd9727-2"></a>{{% thumbnail "/images/foo.png" alt="Foo Image" align="center" %}}{{% /thumbnail %}}
  1233. <a name="rest_code_1361b6c7517446d598a599277dcd9727-3"></a>{{% thumbnail "/images/foo.png" imgclass="image-grayscale" figclass="figure-shadow" %}}&lt;p&gt;Image caption&lt;/p&gt;{{% /thumbnail %}}
  1234. <a name="rest_code_1361b6c7517446d598a599277dcd9727-4"></a>{{% thumbnail "/images/foo.png" alt="Foo Image" title="Insert title-text joke here" align="right" %}}&lt;p class="caption"&gt;Foo Image (right-aligned) caption&lt;/p&gt;{{% /thumbnail %}}
  1235. </pre><p>The following keyword arguments are supported:</p>
  1236. <ul class="simple">
  1237. <li><p>alt (alt text for image)</p></li>
  1238. <li><p>align (image alignment, left/center/right)</p></li>
  1239. <li><p>linktitle (title text for the link, shown by e.g. baguetteBox)</p></li>
  1240. <li><p>title (title text for image)</p></li>
  1241. <li><p>imgclass (class for image)</p></li>
  1242. <li><p>figclass (class for figure, used only if you provide a caption)</p></li>
  1243. </ul>
  1244. <p>Looks similar to the reST thumbnail directive. Caption should be a HTML fragment.</p>
  1245. </dd>
  1246. </dl>
  1247. </section>
  1248. <section id="community-shortcodes">
  1249. <h2><a class="toc-backref" href="#toc-entry-49" role="doc-backlink">Community shortcodes</a></h2>
  1250. <p>Shortcodes created by the community are available in <a class="reference external" href="https://github.com/getnikola/shortcodes">the shortcodes repository on GitHub</a>.</p>
  1251. </section>
  1252. <section id="template-based-shortcodes">
  1253. <h2><a class="toc-backref" href="#toc-entry-50" role="doc-backlink">Template-based shortcodes</a></h2>
  1254. <p>If you put a template in <code class="docutils literal">shortcodes/</code> called <code class="docutils literal">mycode.tmpl</code> then Nikola
  1255. will create a shortcode called <code class="docutils literal">mycode</code> you can use. Any options you pass to
  1256. the shortcode will be available as variables for that template. Non-keyword
  1257. options will be passed in a tuple variable named <code class="docutils literal">_args</code>.</p>
  1258. <p>The post in which the shortcode is being used is available as the <code class="docutils literal">post</code>
  1259. variable, so you can access the title as <code class="docutils literal">post.title</code>, and data loaded
  1260. via the <code class="docutils literal">data</code> field in the metadata using <code class="docutils literal">post.data(key)</code>.</p>
  1261. <p>If you use the shortcode as paired, then the contents between the paired tags
  1262. will be available in the <code class="docutils literal">data</code> variable. If you want to access the Nikola
  1263. object, it will be available as <code class="docutils literal">site</code>. Use with care :-)</p>
  1264. <aside class="admonition note">
  1265. <p class="admonition-title">Note</p>
  1266. <p>Template-based shortcodes use the same template engine as your site’s theme.</p>
  1267. </aside>
  1268. <p>See <a class="reference external" href="/pages/extending.html">Extending Nikola</a> for detailed information.</p>
  1269. <p>For example, if your <code class="docutils literal">shortcodes/foo.tmpl</code> contains this:</p>
  1270. <pre class="code text"><a name="rest_code_6035c8ab23004e31be536b9f949cdba5-1"></a>This uses the bar variable: ${bar}
  1271. </pre><p>And your post contains this:</p>
  1272. <pre class="code text"><a name="rest_code_0bb098b26f0347419ebbf54484a32c1a-1"></a>{{% foo bar=bla %}}
  1273. </pre><p>Then the output file will contain:</p>
  1274. <pre class="code text"><a name="rest_code_0adb60b492ec499d93accd1efb9fcf9d-1"></a>This uses the bar variable: bla
  1275. </pre><p>Finally, you can use a template shortcode without a file, by inserting the
  1276. template in the shortcode itself:</p>
  1277. <pre class="code html+mako"><a name="rest_code_3c12261a69e547b0aac11a3a4a15a504-1"></a>{{% template %}}
  1278. <a name="rest_code_3c12261a69e547b0aac11a3a4a15a504-2"></a><span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
  1279. <a name="rest_code_3c12261a69e547b0aac11a3a4a15a504-3"></a><span class="cp">%</span> <span class="k">for</span> <span class="n">foo</span> <span class="ow">in</span> <span class="n">bar</span><span class="p">:</span>
  1280. <a name="rest_code_3c12261a69e547b0aac11a3a4a15a504-4"></a><span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span><span class="cp">${</span><span class="n">foo</span><span class="cp">}</span><span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  1281. <a name="rest_code_3c12261a69e547b0aac11a3a4a15a504-5"></a><span class="cp">%</span><span class="k"> endfor</span>
  1282. <a name="rest_code_3c12261a69e547b0aac11a3a4a15a504-6"></a><span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
  1283. <a name="rest_code_3c12261a69e547b0aac11a3a4a15a504-7"></a>{{% /template %}}
  1284. </pre><p>In that case, the template engine used will be your theme's and the arguments you pass,
  1285. as well as the global context from your <code class="docutils literal">conf.py</code>, are available to the template you
  1286. are creating.</p>
  1287. <p>You can use anything defined in your configuration's <code class="docutils literal">GLOBAL_CONTEXT</code> as
  1288. variables in your shortcode template, with a caveat: Because of an unfortunate
  1289. implementation detail (a name conflict), <code class="docutils literal">data</code> is called <code class="docutils literal">global_data</code>
  1290. when used in a shortcode.</p>
  1291. <p>If you have some template code that you want to appear in both a template and
  1292. shortcode, you can put the shared code in a separate template and import it in both
  1293. places. Shortcodes can import any template inside <code class="docutils literal">templates/</code> and themes,
  1294. and call any macros defined in those.</p>
  1295. <p>For example, if you define a macro <code class="docutils literal">foo(x, y)</code> in
  1296. <code class="docutils literal">templates/shared_sc.tmpl</code>, you can include <code class="docutils literal">shared_foo.tmpl</code> in
  1297. <code class="docutils literal">templates/special_post.tmpl</code> and <code class="docutils literal">shortcodes/foo.tmpl</code> and then call the
  1298. <code class="docutils literal">${shared_foo.foo(x, y)}</code> macro.</p>
  1299. </section>
  1300. </section>
  1301. <section id="the-global-context-and-data-files">
  1302. <h1><a class="toc-backref" href="#toc-entry-51" role="doc-backlink">The Global Context and Data files</a></h1>
  1303. <p>There is a <code class="docutils literal">GLOBAL_CONTEXT</code> field in your <code class="docutils literal">conf.py</code> where you can
  1304. put things you want to make available to your templates.</p>
  1305. <p>It will also contain things you put in a <code class="docutils literal">data/</code> directory within your
  1306. site. You can use JSON, YAML or TOML files (with the appropriate file
  1307. extensions: json/js, yaml/yml, toml/tml) that decode to Python dictionaries.
  1308. For example, if you create <code class="docutils literal">data/foo.json</code> containing this:</p>
  1309. <pre class="code json"><a name="rest_code_4dc650e3a20246fd809ef23aad762f0e-1"></a><span class="p">{</span><span class="nt">&quot;bar&quot;</span><span class="p">:</span> <span class="s2">&quot;baz&quot;</span><span class="p">}</span>
  1310. </pre><p>Then your templates can use things like <code class="docutils literal"><span class="pre">${data['foo']['bar']}</span></code> and
  1311. it will be replaced by &quot;baz&quot;.</p>
  1312. <p>Individual posts can also have a data file. Those are specified using the
  1313. <code class="docutils literal">data</code> meta field (path relative to <code class="docutils literal">conf.py</code>, can be different in
  1314. different post languages). Those are accessible as eg.
  1315. <code class="docutils literal"><span class="pre">${post.data['bar']}</span></code> in templates. <a class="reference internal" href="#template-based-shortcodes">Template-based shortcodes</a> are a
  1316. good idea in this case.</p>
  1317. <p>Data files can be useful for eg. auto-generated sites, where users provide
  1318. JSON/YAML/TOML files and Nikola generates a large page with data from all data
  1319. files. (This is especially useful with some automatic rebuild feature, like
  1320. those documented in <a class="reference internal" href="#deployment">Deployment</a>)</p>
  1321. <p>Data files are also available as <code class="docutils literal">global_data</code>, to avoid name conflicts in
  1322. shortcodes. (<code class="docutils literal">global_data</code> works everywhere.)</p>
  1323. </section>
  1324. <section id="redirections">
  1325. <h1><a class="toc-backref" href="#toc-entry-52" role="doc-backlink">Redirections</a></h1>
  1326. <p>If you need a page to be available in more than one place, you can define redirections
  1327. in your <code class="docutils literal">conf.py</code>:</p>
  1328. <pre class="code python"><a name="rest_code_f95788d007ac4386a97f12dc20469dac-1"></a><span class="c1"># A list of redirection tuples, [(&quot;foo/from.html&quot;, &quot;/bar/to.html&quot;)].</span>
  1329. <a name="rest_code_f95788d007ac4386a97f12dc20469dac-2"></a><span class="c1">#</span>
  1330. <a name="rest_code_f95788d007ac4386a97f12dc20469dac-3"></a><span class="c1"># A HTML file will be created in output/foo/from.html that redirects</span>
  1331. <a name="rest_code_f95788d007ac4386a97f12dc20469dac-4"></a><span class="c1"># to the &quot;/bar/to.html&quot; URL. notice that the &quot;from&quot; side MUST be a</span>
  1332. <a name="rest_code_f95788d007ac4386a97f12dc20469dac-5"></a><span class="c1"># relative URL.</span>
  1333. <a name="rest_code_f95788d007ac4386a97f12dc20469dac-6"></a><span class="c1">#</span>
  1334. <a name="rest_code_f95788d007ac4386a97f12dc20469dac-7"></a><span class="c1"># If you don&#39;t need any of these, just set to []</span>
  1335. <a name="rest_code_f95788d007ac4386a97f12dc20469dac-8"></a>
  1336. <a name="rest_code_f95788d007ac4386a97f12dc20469dac-9"></a><span class="n">REDIRECTIONS</span> <span class="o">=</span> <span class="p">[(</span><span class="s2">&quot;index.html&quot;</span><span class="p">,</span> <span class="s2">&quot;/weblog/index.html&quot;</span><span class="p">)]</span>
  1337. </pre><p>It's better if you can do these using your web server's configuration, but if
  1338. you can't, this will work.</p>
  1339. </section>
  1340. <section id="configuration">
  1341. <h1><a class="toc-backref" href="#toc-entry-53" role="doc-backlink">Configuration</a></h1>
  1342. <p>The configuration file can be used to customize a lot of what Nikola does. Its
  1343. syntax is python, but if you don't know the language, it still should not be
  1344. terribly hard to grasp.</p>
  1345. <p>By default, the <code class="docutils literal">conf.py</code> file in the root of the Nikola website will be used.
  1346. You can pass a different configuration file to by using the <code class="docutils literal"><span class="pre">--conf</span></code> command line switch.</p>
  1347. <p>The default <code class="docutils literal">conf.py</code> you get with Nikola should be fairly complete, and is quite
  1348. commented.</p>
  1349. <p>You surely want to edit these options:</p>
  1350. <pre class="code python"><a name="rest_code_4da99e4aa3f5496d82635ede892e09e3-1"></a><span class="c1"># Data about this site</span>
  1351. <a name="rest_code_4da99e4aa3f5496d82635ede892e09e3-2"></a><span class="n">BLOG_AUTHOR</span> <span class="o">=</span> <span class="s2">&quot;Your Name&quot;</span> <span class="c1"># (translatable)</span>
  1352. <a name="rest_code_4da99e4aa3f5496d82635ede892e09e3-3"></a><span class="n">BLOG_TITLE</span> <span class="o">=</span> <span class="s2">&quot;Demo Site&quot;</span> <span class="c1"># (translatable)</span>
  1353. <a name="rest_code_4da99e4aa3f5496d82635ede892e09e3-4"></a><span class="n">SITE_URL</span> <span class="o">=</span> <span class="s2">&quot;https://getnikola.com/&quot;</span>
  1354. <a name="rest_code_4da99e4aa3f5496d82635ede892e09e3-5"></a><span class="n">BLOG_EMAIL</span> <span class="o">=</span> <span class="s2">&quot;joe@demo.site&quot;</span>
  1355. <a name="rest_code_4da99e4aa3f5496d82635ede892e09e3-6"></a><span class="n">BLOG_DESCRIPTION</span> <span class="o">=</span> <span class="s2">&quot;This is a demo site for Nikola.&quot;</span> <span class="c1"># (translatable)</span>
  1356. </pre><p>Some options are marked with a (translatable) comment above or right next to
  1357. them. For those options, two types of values can be provided:</p>
  1358. <ul class="simple">
  1359. <li><p>a string, which will be used for all languages</p></li>
  1360. <li><p>a dict of language-value pairs, to have different values in each language</p></li>
  1361. </ul>
  1362. <aside class="admonition note">
  1363. <p class="admonition-title">Note</p>
  1364. <p>As of version 8.0.3 it is possible to create configuration files which inherit values from other Python files.
  1365. This might be useful if you're working with similar environments.</p>
  1366. <dl>
  1367. <dt>Example:</dt>
  1368. <dd><dl>
  1369. <dt>conf.py:</dt>
  1370. <dd><pre class="code python"><a name="rest_code_87474c99ec32407e8f46318d9078dc38-1"></a><span class="n">BLOG_AUTHOR</span> <span class="o">=</span> <span class="s2">&quot;Your Name&quot;</span>
  1371. <a name="rest_code_87474c99ec32407e8f46318d9078dc38-2"></a><span class="n">BLOG_TITLE</span> <span class="o">=</span> <span class="s2">&quot;Demo Site&quot;</span>
  1372. <a name="rest_code_87474c99ec32407e8f46318d9078dc38-3"></a><span class="n">SITE_URL</span> <span class="o">=</span> <span class="s2">&quot;https://yourname.github.io/demo-site</span>
  1373. <a name="rest_code_87474c99ec32407e8f46318d9078dc38-4"></a><span class="n">BLOG_EMAIL</span> <span class="o">=</span> <span class="s2">&quot;joe@demo.site&quot;</span>
  1374. <a name="rest_code_87474c99ec32407e8f46318d9078dc38-5"></a><span class="n">BLOG_DESCRIPTION</span> <span class="o">=</span> <span class="s2">&quot;This is a demo site for Nikola.&quot;</span>
  1375. </pre></dd>
  1376. <dt>debug.conf.py:</dt>
  1377. <dd><pre class="code python"><a name="rest_code_cfcf7893d7434f33aff1a30ef65edc10-1"></a><span class="kn">import</span> <span class="nn">conf</span>
  1378. <a name="rest_code_cfcf7893d7434f33aff1a30ef65edc10-2"></a><span class="nb">globals</span><span class="p">()</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="nb">vars</span><span class="p">(</span><span class="n">conf</span><span class="p">))</span>
  1379. <a name="rest_code_cfcf7893d7434f33aff1a30ef65edc10-3"></a><span class="n">SITE_URL</span> <span class="o">=</span> <span class="s2">&quot;http://localhost:8000/&quot;</span>
  1380. </pre><p>or</p>
  1381. <pre class="code python"><a name="rest_code_7263480f318a4ad2808bb1440153a1f8-1"></a><span class="kn">from</span> <span class="nn">conf</span> <span class="kn">import</span> <span class="o">*</span>
  1382. <a name="rest_code_7263480f318a4ad2808bb1440153a1f8-2"></a><span class="n">SITE_URL</span> <span class="o">=</span> <span class="s2">&quot;http://localhost:8000/&quot;</span>
  1383. </pre></dd>
  1384. </dl>
  1385. </dd>
  1386. </dl>
  1387. </aside>
  1388. </section>
  1389. <section id="customizing-your-site">
  1390. <h1><a class="toc-backref" href="#toc-entry-54" role="doc-backlink">Customizing Your Site</a></h1>
  1391. <p>There are lots of things you can do to personalize your website, but let's see
  1392. the easy ones!</p>
  1393. <dl>
  1394. <dt>CSS tweaking</dt>
  1395. <dd><p>Using the default configuration, you can create a <code class="docutils literal">assets/css/custom.css</code>
  1396. file under <code class="docutils literal">files/</code> or in your theme and then it will be loaded from the
  1397. <code class="docutils literal">&lt;head&gt;</code> blocks of your site pages. Create it and put your CSS code there,
  1398. for minimal disruption of the provided CSS files.</p>
  1399. <p>If you feel tempted to touch other files in assets, you probably will be better off
  1400. with a <a class="reference external" href="/pages/theming.html">custom theme</a>.</p>
  1401. <p>If you want to use <a class="reference external" href="http://lesscss.org/">LESS</a> or <a class="reference external" href="https://sass-lang.com/">Sass</a> for your custom CSS, or the theme you use
  1402. contains LESS or Sass code that you want to override, you will need to install
  1403. the <a class="reference external" href="https://plugins.getnikola.com/#less">LESS plugin</a> or
  1404. <a class="reference external" href="https://plugins.getnikola.com/#sass">SASS plugin</a> create a <code class="docutils literal">less</code> or
  1405. <code class="docutils literal">sass</code> directory in your site root, put your <code class="docutils literal">.less</code> or <code class="docutils literal">.scss</code> files
  1406. there and a targets file containing the list of files you want compiled.</p>
  1407. </dd>
  1408. </dl>
  1409. <dl>
  1410. <dt>Template tweaking and creating themes</dt>
  1411. <dd><p>If you really want to change the pages radically, you will want to do a
  1412. <a class="reference external" href="/pages/theming.html">custom theme</a>.</p>
  1413. </dd>
  1414. <dt>Navigation Links</dt>
  1415. <dd><p>The <code class="docutils literal">NAVIGATION_LINKS</code> option lets you define what links go in a sidebar or menu
  1416. (depending on your theme) so you can link to important pages, or to other sites.</p>
  1417. <p>The format is a language-indexed dictionary, where each element is a tuple of
  1418. tuples which are one of:</p>
  1419. <ol class="arabic simple">
  1420. <li><p>A (url, text) tuple, describing a link</p></li>
  1421. <li><p>A (((url, text), (url, text), (url, text)), title) tuple, describing a submenu / sublist.</p></li>
  1422. </ol>
  1423. <p>Example:</p>
  1424. <pre class="code python"><a name="rest_code_2ac806e68e064632b07a82714691b167-1"></a><span class="n">NAVIGATION_LINKS</span> <span class="o">=</span> <span class="p">{</span>
  1425. <a name="rest_code_2ac806e68e064632b07a82714691b167-2"></a> <span class="n">DEFAULT_LANG</span><span class="p">:</span> <span class="p">(</span>
  1426. <a name="rest_code_2ac806e68e064632b07a82714691b167-3"></a> <span class="p">(</span><span class="s1">&#39;/archive.html&#39;</span><span class="p">,</span> <span class="s1">&#39;Archives&#39;</span><span class="p">),</span>
  1427. <a name="rest_code_2ac806e68e064632b07a82714691b167-4"></a> <span class="p">(</span><span class="s1">&#39;/categories/index.html&#39;</span><span class="p">,</span> <span class="s1">&#39;Tags&#39;</span><span class="p">),</span>
  1428. <a name="rest_code_2ac806e68e064632b07a82714691b167-5"></a> <span class="p">(</span><span class="s1">&#39;/rss.xml&#39;</span><span class="p">,</span> <span class="s1">&#39;RSS&#39;</span><span class="p">),</span>
  1429. <a name="rest_code_2ac806e68e064632b07a82714691b167-6"></a> <span class="p">(((</span><span class="s1">&#39;/foo&#39;</span><span class="p">,</span> <span class="s1">&#39;FOO&#39;</span><span class="p">),</span>
  1430. <a name="rest_code_2ac806e68e064632b07a82714691b167-7"></a> <span class="p">(</span><span class="s1">&#39;/bar&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">)),</span> <span class="s1">&#39;BAZ&#39;</span><span class="p">),</span>
  1431. <a name="rest_code_2ac806e68e064632b07a82714691b167-8"></a> <span class="p">),</span>
  1432. <a name="rest_code_2ac806e68e064632b07a82714691b167-9"></a><span class="p">}</span>
  1433. </pre><aside class="admonition note">
  1434. <p class="admonition-title">Note</p>
  1435. <ol class="arabic simple">
  1436. <li><p>Support for submenus is theme-dependent. Only one level of
  1437. submenus is supported.</p></li>
  1438. <li><p>Some themes, including the default Bootstrap theme, may
  1439. present issues if the menu is too large. (in Bootstrap, the navbar
  1440. can grow too large and cover contents.)</p></li>
  1441. <li><p>If you link to directories, make sure to follow <code class="docutils literal">STRIP_INDEXES</code>. If
  1442. it’s set to <code class="docutils literal">True</code>, end your links with a <code class="docutils literal">/</code>, otherwise end them
  1443. with <code class="docutils literal">/index.html</code> — or else they won’t be highlighted when active.</p></li>
  1444. </ol>
  1445. </aside>
  1446. <p>There’s also <code class="docutils literal">NAVIGATION_ALT_LINKS</code>. Themes may display this somewhere
  1447. else, or not at all. Bootstrap puts it on the right side of the header.</p>
  1448. <p>The <code class="docutils literal">SEARCH_FORM</code> option contains the HTML code for a search form based on
  1449. duckduckgo.com which should always work, but feel free to change it to
  1450. something else.</p>
  1451. </dd>
  1452. <dt>Footer</dt>
  1453. <dd><p><code class="docutils literal">CONTENT_FOOTER</code> is displayed, small at the bottom of all pages, I use it for
  1454. the copyright notice. The default shows a text formed using <code class="docutils literal">BLOG_AUTHOR</code>,
  1455. <code class="docutils literal">BLOG_EMAIL</code>, the date and <code class="docutils literal">LICENSE</code>. Note you need to use
  1456. <code class="docutils literal">CONTENT_FOOTER_FORMATS</code> instead of regular str.format or %-formatting,
  1457. for compatibility with the translatable settings feature.</p>
  1458. </dd>
  1459. <dt>BODY_END</dt>
  1460. <dd><p>This option lets you define a HTML snippet that will be added at the bottom of body.
  1461. The main usage is a Google analytics snippet or something similar, but you can really
  1462. put anything there. Good place for JavaScript.</p>
  1463. </dd>
  1464. <dt>SOCIAL_BUTTONS_CODE</dt>
  1465. <dd><p>The <code class="docutils literal">SOCIAL_BUTTONS_CODE</code> option lets you define a HTML snippet that will be added
  1466. at the bottom of body. It defaults to a snippet for AddThis, but you can
  1467. really put anything there. See <cite>social_buttons.html</cite> for more details.</p>
  1468. </dd>
  1469. </dl>
  1470. </section>
  1471. <section id="fancy-dates">
  1472. <h1><a class="toc-backref" href="#toc-entry-55" role="doc-backlink">Fancy Dates</a></h1>
  1473. <p>Nikola can use various styles for presenting dates.</p>
  1474. <dl class="simple">
  1475. <dt>DATE_FORMAT</dt>
  1476. <dd><p>The date format to use if there is no JS or fancy dates are off. <a class="reference external" href="http://cldr.unicode.org/translation/date-time-1/date-time">Compatible with CLDR syntax.</a></p>
  1477. </dd>
  1478. <dt>LUXON_DATE_FORMAT</dt>
  1479. <dd><p>The date format to use with Luxon. A dictionary of dictionaries: the top level is languages, and the subdictionaries are of the format <code class="docutils literal">{'preset': False, 'format': <span class="pre">'yyyy-MM-dd</span> HH:mm'}</code>. <a class="reference external" href="https://moment.github.io/luxon/docs/manual/formatting">Used by Luxon</a> (format can be the preset name, eg. <code class="docutils literal">'DATE_LONG'</code>).</p>
  1480. </dd>
  1481. <dt>MOMENTJS_DATE_FORMAT (formerly JS_DATE_FORMAT)</dt>
  1482. <dd><p>The date format to use if fancy dates are on, and the theme is using Moment.js.</p>
  1483. </dd>
  1484. <dt>DATE_FANCINESS = 0</dt>
  1485. <dd><p>Fancy dates are off, and DATE_FORMAT is used.</p>
  1486. </dd>
  1487. <dt>DATE_FANCINESS = 1</dt>
  1488. <dd><p>Dates are recalculated in user’s timezone. Requires JavaScript.</p>
  1489. </dd>
  1490. <dt>DATE_FANCINESS = 2</dt>
  1491. <dd><p>Dates are recalculated as relative time (eg. 2 days ago). Requires JavaScript.</p>
  1492. </dd>
  1493. </dl>
  1494. <p>In order to use fancy dates, your theme must support them. The built-in Bootstrap family supports it, but other themes might not by default.</p>
  1495. <p>For Mako:</p>
  1496. <pre class="code html"><a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-1"></a>% if date_fanciness != 0:
  1497. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-2"></a>%if date_fanciness == 2:
  1498. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-3"></a> <span class="c">&lt;!-- Polyfill for relative dates in Safari -- best handled with a CDN --&gt;</span>
  1499. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-4"></a> <span class="p">&lt;</span><span class="nt">script</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;https://polyfill.io/v3/polyfill.js?features=Intl.RelativeTimeFormat.%7Elocale.${luxon_locales[lang]}&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
  1500. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-5"></a>%endif
  1501. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-6"></a><span class="c">&lt;!-- required scripts -- best handled with bundles --&gt;</span>
  1502. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-7"></a><span class="p">&lt;</span><span class="nt">script</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;/assets/js/luxon.min.js&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
  1503. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-8"></a><span class="p">&lt;</span><span class="nt">script</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;/assets/js/fancydates.js&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
  1504. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-9"></a>
  1505. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-10"></a><span class="c">&lt;!-- fancy dates code --&gt;</span>
  1506. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-11"></a><span class="p">&lt;</span><span class="nt">script</span><span class="p">&gt;</span>
  1507. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-12"></a><span class="nx">luxon</span><span class="p">.</span><span class="nx">Settings</span><span class="p">.</span><span class="nx">defaultLocale</span> <span class="o">=</span> <span class="s2">&quot;${luxon_locales[lang]}&quot;</span><span class="p">;</span>
  1508. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-13"></a><span class="nx">fancydates</span><span class="p">(</span><span class="nx">$</span><span class="p">{</span><span class="nx">date_fanciness</span><span class="p">},</span> <span class="nx">$</span><span class="p">{</span><span class="nx">luxon_date_format</span><span class="p">});</span>
  1509. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-14"></a><span class="p">&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
  1510. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-15"></a><span class="c">&lt;!-- end fancy dates code --&gt;</span>
  1511. <a name="rest_code_b81e3d14c71445e0a6d3590aeaba7932-16"></a>%endif
  1512. </pre><p>For Jinja2:</p>
  1513. <pre class="code html"><a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-1"></a>{% if date_fanciness != 0 %}
  1514. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-2"></a>{% if date_fanciness == 2 %}
  1515. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-3"></a> <span class="c">&lt;!-- Polyfill for relative dates in Safari -- best handled with a CDN --&gt;</span>
  1516. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-4"></a> <span class="p">&lt;</span><span class="nt">script</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;https://polyfill.io/v3/polyfill.js?features=Intl.RelativeTimeFormat.%7Elocale.{{ luxon_locales[lang] }}&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
  1517. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-5"></a>{% endif %}
  1518. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-6"></a><span class="c">&lt;!-- required scripts -- best handled with bundles --&gt;</span>
  1519. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-7"></a><span class="p">&lt;</span><span class="nt">script</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;/assets/js/luxon.min.js&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
  1520. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-8"></a><span class="p">&lt;</span><span class="nt">script</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;/assets/js/fancydates.js&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
  1521. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-9"></a>
  1522. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-10"></a><span class="c">&lt;!-- fancy dates code --&gt;</span>
  1523. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-11"></a><span class="p">&lt;</span><span class="nt">script</span><span class="p">&gt;</span>
  1524. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-12"></a><span class="nx">luxon</span><span class="p">.</span><span class="nx">Settings</span><span class="p">.</span><span class="nx">defaultLocale</span> <span class="o">=</span> <span class="s2">&quot;{{ luxon_locales[lang] }}&quot;</span><span class="p">;</span>
  1525. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-13"></a><span class="nx">fancydates</span><span class="p">({{</span> <span class="nx">date_fanciness</span> <span class="p">}},</span> <span class="p">{{</span> <span class="nx">luxon_date_format</span> <span class="p">}});</span>
  1526. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-14"></a><span class="p">&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
  1527. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-15"></a><span class="c">&lt;!-- end fancy dates code --&gt;</span>
  1528. <a name="rest_code_5a2dc5b84dd546e4bc7b4677b9260978-16"></a>{% endif %}
  1529. </pre></section>
  1530. <section id="adding-files">
  1531. <h1><a class="toc-backref" href="#toc-entry-56" role="doc-backlink">Adding Files</a></h1>
  1532. <p>Any files you want to be in <code class="docutils literal">output/</code> but are not generated by Nikola (for
  1533. example, <code class="docutils literal">favicon.ico</code>) should be placed in <code class="docutils literal">files/</code>. Remember that you
  1534. can't have files that collide with files Nikola generates (it will give an
  1535. error).</p>
  1536. <aside class="admonition admonition-important">
  1537. <p class="admonition-title">Important</p>
  1538. <p>Don't put any files manually in <code class="docutils literal">output/</code>. Ever. Really.
  1539. Maybe someday Nikola will just wipe <code class="docutils literal">output/</code> (when you run <code class="docutils literal">nikola check <span class="pre">-f</span> <span class="pre">--clean-files</span></code>) and then you will be sorry. So, please don't do that.</p>
  1540. </aside>
  1541. <p>If you want to copy more than one folder of static files into <code class="docutils literal">output</code> you can
  1542. change the FILES_FOLDERS option:</p>
  1543. <pre class="code python"><a name="rest_code_09e5165e8fff4f77ae2e570ef43b950c-1"></a><span class="c1"># One or more folders containing files to be copied as-is into the output.</span>
  1544. <a name="rest_code_09e5165e8fff4f77ae2e570ef43b950c-2"></a><span class="c1"># The format is a dictionary of &quot;source&quot; &quot;relative destination&quot;.</span>
  1545. <a name="rest_code_09e5165e8fff4f77ae2e570ef43b950c-3"></a><span class="c1"># Default is:</span>
  1546. <a name="rest_code_09e5165e8fff4f77ae2e570ef43b950c-4"></a><span class="c1"># FILES_FOLDERS = {&#39;files&#39;: &#39;&#39; }</span>
  1547. <a name="rest_code_09e5165e8fff4f77ae2e570ef43b950c-5"></a><span class="c1"># Which means copy &#39;files&#39; into &#39;output&#39;</span>
  1548. </pre></section>
  1549. <section id="custom-themes">
  1550. <h1><a class="toc-backref" href="#toc-entry-57" role="doc-backlink">Custom Themes</a></h1>
  1551. <p>If you prefer to have a custom appearance for your site, and modifying CSS
  1552. files and settings (see <a class="reference internal" href="#customizing-your-site">Customizing Your Site</a> for details) is not enough,
  1553. you can create your own theme. See the <a class="reference external" href="/pages/theming.html">Theming Nikola</a> and
  1554. <a class="reference external" href="/pages/creating-a-theme.html">Creating a Theme</a> for more details. You can put them in a <code class="docutils literal">themes/</code>
  1555. folder and set <code class="docutils literal">THEME</code> to the directory name. You can also put them in
  1556. directories listed in the <code class="docutils literal">EXTRA_THEMES_DIRS</code> configuration variable.</p>
  1557. </section>
  1558. <section id="getting-extra-themes">
  1559. <h1><a class="toc-backref" href="#toc-entry-58" role="doc-backlink">Getting Extra Themes</a></h1>
  1560. <p>There are a few themes for Nikola. They are available at
  1561. the <a class="reference external" href="https://themes.getnikola.com/">Themes Index</a>.
  1562. Nikola has a built-in theme download/install mechanism to install those themes
  1563. — the <code class="docutils literal">theme</code> command:</p>
  1564. <pre class="code console"><a name="rest_code_f2f92738a0074fba924eafed3daacedb-1"></a><span class="gp">$</span> nikola theme -l
  1565. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-2"></a><span class="go">Themes:</span>
  1566. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-3"></a><span class="go">-------</span>
  1567. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-4"></a><span class="go">blogtxt</span>
  1568. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-5"></a><span class="go">bootstrap3-gradients</span>
  1569. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-6"></a><span class="go">⋮</span>
  1570. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-7"></a><span class="go">⋮</span>
  1571. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-8"></a>
  1572. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-9"></a><span class="gp">$</span> nikola theme -i blogtxt
  1573. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-10"></a><span class="go">[2013-10-12T16:46:13Z] NOTICE: theme: Downloading:</span>
  1574. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-11"></a><span class="go">https://themes.getnikola.com/v6/blogtxt.zip</span>
  1575. <a name="rest_code_f2f92738a0074fba924eafed3daacedb-12"></a><span class="go">[2013-10-12T16:46:15Z] NOTICE: theme: Extracting: blogtxt into themes</span>
  1576. </pre><p>And there you are, you now have themes/blogtxt installed. It's very
  1577. rudimentary, but it should work in most cases.</p>
  1578. <p>If you create a nice theme, please share it! You can do it as a pull
  1579. request in the <a class="reference external" href="https://github.com/getnikola/nikola-themes">GitHub repository</a>.</p>
  1580. <p>One other option is to tweak an existing theme using a different color scheme,
  1581. typography and CSS in general. Nikola provides a <code class="docutils literal">subtheme</code> command
  1582. to create a custom theme by downloading free CSS files from <a class="reference external" href="https://bootswatch.com">https://bootswatch.com</a>
  1583. and <a class="reference external" href="https://hackerthemes.com">https://hackerthemes.com</a></p>
  1584. <pre class="code console"><a name="rest_code_f85a98af5f764ca581778646283fe1d4-1"></a><span class="gp">$</span> nikola subtheme -n custom_theme -s flatly -p bootstrap4
  1585. <a name="rest_code_f85a98af5f764ca581778646283fe1d4-2"></a><span class="go">[2013-10-12T16:46:58Z] NOTICE: subtheme: Creating &#39;custom_theme&#39; theme</span>
  1586. <a name="rest_code_f85a98af5f764ca581778646283fe1d4-3"></a><span class="go">from &#39;flatly&#39; and &#39;bootstrap4&#39;</span>
  1587. <a name="rest_code_f85a98af5f764ca581778646283fe1d4-4"></a><span class="go">[2013-10-12T16:46:58Z] NOTICE: subtheme: Downloading:</span>
  1588. <a name="rest_code_f85a98af5f764ca581778646283fe1d4-5"></a><span class="go">http://bootswatch.com/flatly/bootstrap.min.css</span>
  1589. <a name="rest_code_f85a98af5f764ca581778646283fe1d4-6"></a><span class="go">[2013-10-12T16:46:58Z] NOTICE: subtheme: Downloading:</span>
  1590. <a name="rest_code_f85a98af5f764ca581778646283fe1d4-7"></a><span class="go">http://bootswatch.com/flatly/bootstrap.css</span>
  1591. <a name="rest_code_f85a98af5f764ca581778646283fe1d4-8"></a><span class="go">[2013-10-12T16:46:59Z] NOTICE: subtheme: Theme created. Change the THEME setting to &quot;custom_theme&quot; to use it.</span>
  1592. </pre><p>Play with it, there's cool stuff there. This feature was suggested by
  1593. <a class="reference external" href="http://elgalpondebanquito.com.ar">clodo</a>.</p>
  1594. </section>
  1595. <section id="deployment">
  1596. <h1><a class="toc-backref" href="#toc-entry-59" role="doc-backlink">Deployment</a></h1>
  1597. <p>If you can specify your deployment procedure as a series of commands, you can
  1598. put them in the <code class="docutils literal">DEPLOY_COMMANDS</code> option, and run them with <code class="docutils literal">nikola deploy</code>.</p>
  1599. <p>You can have multiple deployment presets. If you run <code class="docutils literal">nikola deploy</code>, the
  1600. <code class="docutils literal">default</code> preset is executed. You can also specify the names of presets
  1601. you want to run (eg. <code class="docutils literal">nikola deploy default</code>, multiple presets are allowed).</p>
  1602. <p>One caveat is that if any command has a % in it, you should double them.</p>
  1603. <p>Here is an example, from my own site's deployment script:</p>
  1604. <pre class="code python"><a name="rest_code_59a2999f62f44b56ac9e57ae60039238-1"></a><span class="n">DEPLOY_COMMANDS</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;default&#39;</span><span class="p">:</span> <span class="p">[</span>
  1605. <a name="rest_code_59a2999f62f44b56ac9e57ae60039238-2"></a> <span class="s1">&#39;rsync -rav --delete output/ ralsina@lateral.netmanagers.com.ar:/srv/www/lateral&#39;</span><span class="p">,</span>
  1606. <a name="rest_code_59a2999f62f44b56ac9e57ae60039238-3"></a> <span class="s1">&#39;rdiff-backup output ~/blog-backup&#39;</span><span class="p">,</span>
  1607. <a name="rest_code_59a2999f62f44b56ac9e57ae60039238-4"></a> <span class="s2">&quot;links -dump &#39;http://www.twingly.com/ping2?url=lateral.netmanagers.com.ar&#39;&quot;</span><span class="p">,</span>
  1608. <a name="rest_code_59a2999f62f44b56ac9e57ae60039238-5"></a><span class="p">]}</span>
  1609. </pre><p>Other interesting ideas are using
  1610. <a class="reference external" href="https://toroid.org/git-website-howto">git as a deployment mechanism</a> (or any other VCS
  1611. for that matter), using <a class="reference external" href="https://lftp.yar.ru/">lftp mirror</a> or unison, or Dropbox.
  1612. Any way you can think of to copy files from one place to another is good enough.</p>
  1613. <section id="deploying-to-github">
  1614. <h2><a class="toc-backref" href="#toc-entry-60" role="doc-backlink">Deploying to GitHub</a></h2>
  1615. <p>Nikola provides a separate command <code class="docutils literal">github_deploy</code> to deploy your site to
  1616. GitHub Pages. The command builds the site, commits the output to a gh-pages
  1617. branch and pushes the output to GitHub. Nikola uses the <a class="reference external" href="https://github.com/davisp/ghp-import">ghp-import command</a> for this.</p>
  1618. <p>In order to use this feature, you need to configure a few things first. Make
  1619. sure you have <code class="docutils literal">nikola</code> and <code class="docutils literal">git</code> installed on your PATH.</p>
  1620. <ol class="arabic">
  1621. <li><p>Initialize a Nikola site, if you haven’t already.</p></li>
  1622. <li><p>Initialize a git repository in your Nikola source directory by running:</p>
  1623. <pre class="code text"><a name="rest_code_a15b8909505542b9a3d2dab06521e85e-1"></a>git init .
  1624. <a name="rest_code_a15b8909505542b9a3d2dab06521e85e-2"></a>git remote add origin git@github.com:user/repository.git
  1625. </pre></li>
  1626. <li><p>Setup branches and remotes in <code class="docutils literal">conf.py</code>:</p>
  1627. <ul class="simple">
  1628. <li><p><code class="docutils literal">GITHUB_DEPLOY_BRANCH</code> is the branch where Nikola-generated HTML files
  1629. will be deployed. It should be <code class="docutils literal"><span class="pre">gh-pages</span></code> for project pages and
  1630. <code class="docutils literal">master</code> for user pages (user.github.io).</p></li>
  1631. <li><p><code class="docutils literal">GITHUB_SOURCE_BRANCH</code> is the branch where your Nikola site source will be
  1632. deployed. We recommend and default to <code class="docutils literal">src</code>.</p></li>
  1633. <li><p><code class="docutils literal">GITHUB_REMOTE_NAME</code> is the remote to which changes are pushed.</p></li>
  1634. <li><p><code class="docutils literal">GITHUB_COMMIT_SOURCE</code> controls whether or not the source branch is
  1635. automatically committed to and pushed. We recommend setting it to
  1636. <code class="docutils literal">True</code>, unless you are automating builds with CI (eg. GitHub Actions/GitLab CI).</p></li>
  1637. </ul>
  1638. </li>
  1639. <li><p>Create a <code class="docutils literal">.gitignore</code> file. We recommend adding at least the following entries:</p>
  1640. <pre class="code text"><a name="rest_code_90245400f63d48fb926bf20a090dd223-1"></a>cache
  1641. <a name="rest_code_90245400f63d48fb926bf20a090dd223-2"></a>.doit.db
  1642. <a name="rest_code_90245400f63d48fb926bf20a090dd223-3"></a>__pycache__
  1643. <a name="rest_code_90245400f63d48fb926bf20a090dd223-4"></a>output
  1644. </pre></li>
  1645. <li><p>If you set <code class="docutils literal">GITHUB_COMMIT_SOURCE</code> to False, you must switch to your source
  1646. branch and commit to it. Otherwise, this is done for you.</p></li>
  1647. <li><p>Run <code class="docutils literal">nikola github_deploy</code>. This will build the site, commit the output
  1648. folder to your deploy branch, and push to GitHub. Your website should be up
  1649. and running within a few minutes.</p></li>
  1650. </ol>
  1651. <p>If you want to use a custom domain, create your <code class="docutils literal">CNAME</code> file in
  1652. <code class="docutils literal">files/CNAME</code> on the source branch. Nikola will copy it to the
  1653. output directory. To add a custom commit message, use the <code class="docutils literal"><span class="pre">-m</span></code> option,
  1654. followed by your message.</p>
  1655. </section>
  1656. <section id="automated-rebuilds-github-actions-gitlab">
  1657. <h2><a class="toc-backref" href="#toc-entry-61" role="doc-backlink">Automated rebuilds (GitHub Actions, GitLab)</a></h2>
  1658. <p>If you want automated rebuilds and GitHub Pages deployment, allowing you to
  1659. blog from anywhere in the world, you have multiple options:</p>
  1660. <ul class="simple">
  1661. <li><p><a class="reference external" href="https://getnikola.com/blog/automating-nikola-rebuilds-with-github-actions.html">Automating Nikola rebuilds with GitHub Actions</a> (easier for GitHub)</p></li>
  1662. <li><p><a class="reference external" href="https://gitlab.com/pages/nikola">Example Nikola site for GitLab Pages</a></p></li>
  1663. </ul>
  1664. </section>
  1665. </section>
  1666. <section id="comments">
  1667. <h1><a class="toc-backref" href="#toc-entry-62" role="doc-backlink">Comments</a></h1>
  1668. <p>While Nikola creates static sites, there is a minimum level of user interaction you
  1669. are probably expecting: comments.</p>
  1670. <p>Nikola supports several third party comment systems:</p>
  1671. <ul class="simple">
  1672. <li><p><a class="reference external" href="https://disqus.com">DISQUS</a></p></li>
  1673. <li><p><a class="reference external" href="https://www.intensedebate.com/">IntenseDebate</a></p></li>
  1674. <li><p><a class="reference external" href="https://muut.com/">Muut (Formerly moot)</a></p></li>
  1675. <li><p><a class="reference external" href="https://facebook.com/">Facebook</a></p></li>
  1676. <li><p><a class="reference external" href="https://posativ.org/isso/">Isso</a></p></li>
  1677. <li><p><a class="reference external" href="https://github.com/adtac/commento">Commento</a></p></li>
  1678. <li><p><a class="reference external" href="https://utteranc.es/">Utterances</a></p></li>
  1679. </ul>
  1680. <p>By default it will use DISQUS, but you can change by setting <code class="docutils literal">COMMENT_SYSTEM</code>
  1681. to one of &quot;disqus&quot;, &quot;intensedebate&quot;, &quot;livefyre&quot;, &quot;moot&quot;, &quot;facebook&quot;, &quot;isso&quot;, &quot;commento&quot; or &quot;utterances&quot;.
  1682. It is also possible to use a comment system added by a plugin, see the
  1683. <a class="reference external" href="https://plugins.getnikola.com/#cactuscomments">Cactus Comments plugin</a> for an example.</p>
  1684. <aside class="sidebar">
  1685. <p class="sidebar-title"><code class="docutils literal">COMMENT_SYSTEM_ID</code></p>
  1686. <p>The value of <code class="docutils literal">COMMENT_SYSTEM_ID</code> depends on what comment system you
  1687. are using and you can see it in the system's admin interface.</p>
  1688. <ul class="simple">
  1689. <li><p>For DISQUS, it's called the <strong>shortname</strong></p></li>
  1690. <li><p>For IntenseDebate, it's the <strong>IntenseDebate site acct</strong></p></li>
  1691. <li><p>For Muut, it's your <strong>username</strong></p></li>
  1692. <li><p>For Facebook, you need to <a class="reference external" href="https://developers.facebook.com/apps">create an app</a> (turn off sandbox mode!)
  1693. and get an <strong>App ID</strong></p></li>
  1694. <li><p>For Isso, it's the URL of your Isso instance (must be world-accessible, encoded with
  1695. Punycode (if using Internationalized Domain Names) and <strong>have a trailing slash</strong>,
  1696. default <code class="docutils literal"><span class="pre">http://localhost:8080/</span></code>). You can add custom config options via
  1697. <code class="docutils literal">GLOBAL_CONTEXT</code>, e.g., <code class="docutils literal"><span class="pre">GLOBAL_CONTEXT['isso_config']</span> = <span class="pre">{&quot;require-author&quot;:</span> &quot;true&quot;}</code></p></li>
  1698. <li><p>For Commento, it's the URL of the commento instance as required by the <code class="docutils literal">serverUrl</code>
  1699. parameter in commento's documentation.</p></li>
  1700. <li><p>For Utterances, it's the <strong>repo name</strong> (<code class="docutils literal">&quot;org/user&quot;</code>) on GitHub whose
  1701. issue tracker is used for comments. Additional Utterances configuration
  1702. values can be stored in the <code class="docutils literal">GLOBAL_CONTEXT</code>, e.g.,
  1703. <code class="docutils literal"><span class="pre">GLOBAL_CONTEXT['utterances_config']</span> = <span class="pre">{&quot;issue-term&quot;:</span> &quot;title&quot;,
  1704. &quot;label&quot;: &quot;Comments&quot;, &quot;theme&quot;: <span class="pre">&quot;github-light&quot;,</span> &quot;crossorigin&quot;: &quot;anonymous&quot;)</code>.</p></li>
  1705. </ul>
  1706. </aside>
  1707. <p>To use comments in a visible site, you should register with the service and
  1708. then set the <code class="docutils literal">COMMENT_SYSTEM_ID</code> option.</p>
  1709. <p>I recommend 3rd party comments, and specially DISQUS because:</p>
  1710. <ol class="arabic simple">
  1711. <li><p>It doesn't require any server-side software on your site</p></li>
  1712. <li><p>They offer you a way to export your comments, so you can take
  1713. them with you if you need to.</p></li>
  1714. <li><p>It's free.</p></li>
  1715. <li><p>It's damn nice.</p></li>
  1716. </ol>
  1717. <p>You can disable comments for a post by adding a &quot;nocomments&quot; metadata field to it:</p>
  1718. <pre class="code restructuredtext"><a name="rest_code_525b990adf414fd08e4d6266a1116147-1"></a><span class="cp">.. nocomments: True</span>
  1719. </pre><aside class="admonition admonition-disqus-support">
  1720. <p class="admonition-title">DISQUS Support</p>
  1721. <p>In some cases, when you run the test site, you won't see the comments.
  1722. That can be fixed by adding the disqus_developer flag to the templates
  1723. but it's probably more trouble than it's worth.</p>
  1724. </aside>
  1725. <aside class="admonition admonition-moot-support">
  1726. <p class="admonition-title">Moot Support</p>
  1727. <p>Moot doesn't support comment counts on index pages, and it requires adding
  1728. this to your <code class="docutils literal">conf.py</code>:</p>
  1729. <pre class="code python"><a name="rest_code_5c61e269dd714e42bd2cb04e330a4be5-1"></a><span class="n">BODY_END</span> <span class="o">=</span> <span class="s2">&quot;&quot;&quot;</span>
  1730. <a name="rest_code_5c61e269dd714e42bd2cb04e330a4be5-2"></a><span class="s2">&lt;script src=&quot;//cdn.moot.it/1/moot.min.js&quot;&gt;&lt;/script&gt;</span>
  1731. <a name="rest_code_5c61e269dd714e42bd2cb04e330a4be5-3"></a><span class="s2">&quot;&quot;&quot;</span>
  1732. <a name="rest_code_5c61e269dd714e42bd2cb04e330a4be5-4"></a><span class="n">EXTRA_HEAD_DATA</span> <span class="o">=</span> <span class="s2">&quot;&quot;&quot;</span>
  1733. <a name="rest_code_5c61e269dd714e42bd2cb04e330a4be5-5"></a><span class="s2">&lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;//cdn.moot.it/1/moot.css&quot;&gt;</span>
  1734. <a name="rest_code_5c61e269dd714e42bd2cb04e330a4be5-6"></a><span class="s2">&lt;meta name=&quot;viewport&quot; content=&quot;width=device-width&quot;&gt;</span>
  1735. <a name="rest_code_5c61e269dd714e42bd2cb04e330a4be5-7"></a><span class="s2">&lt;meta http-equiv=&quot;X-UA-Compatible&quot; content=&quot;IE=edge,chrome=1&quot;&gt;</span>
  1736. <a name="rest_code_5c61e269dd714e42bd2cb04e330a4be5-8"></a><span class="s2">&quot;&quot;&quot;</span>
  1737. </pre></aside>
  1738. <aside class="admonition admonition-facebook-support">
  1739. <p class="admonition-title">Facebook Support</p>
  1740. <p>You need jQuery, but not because Facebook wants it (see Issue
  1741. #639).</p>
  1742. </aside>
  1743. <aside class="admonition admonition-utterances-support">
  1744. <p class="admonition-title">Utterances Support</p>
  1745. <p>You can copy the configuration options from the <a class="reference external" href="https://utteranc.es">Utterances setup page</a> into <code class="docutils literal"><span class="pre">GLOBAL_CONTEXT['utterances_config']</span></code>,
  1746. except for <code class="docutils literal">repo</code>, which should be set as <code class="docutils literal">COMMENT_SYSTEM_ID</code>. Note
  1747. that the either <code class="docutils literal"><span class="pre">issue-term</span></code> or <code class="docutils literal"><span class="pre">issue-number</span></code> must be provided. All
  1748. other Utterances configuration options are optional.</p>
  1749. </aside>
  1750. </section>
  1751. <section id="images-and-galleries">
  1752. <h1><a class="toc-backref" href="#toc-entry-63" role="doc-backlink">Images and Galleries</a></h1>
  1753. <p>To create an image gallery, all you have to do is add a folder inside <code class="docutils literal">galleries</code>,
  1754. and put images there. Nikola will take care of creating thumbnails, index page, etc.</p>
  1755. <p>If you click on images on a gallery, or on images with links in post, you will
  1756. see a bigger image, thanks to the excellent <a class="reference external" href="https://feimosi.github.io/baguetteBox.js/">baguetteBox</a>. If don’t want this behavior, add an
  1757. <code class="docutils literal">.islink</code> class to your link.</p>
  1758. <p>The gallery pages are generated using the <code class="docutils literal">gallery.tmpl</code> template, and you can
  1759. customize it there (you could switch to another lightbox instead of baguetteBox, change
  1760. its settings, change the layout, etc.).</p>
  1761. <p>Images in galleries may be provided with captions and given a specific
  1762. ordering, by creating a file in the gallery directory called <code class="docutils literal">metadata.yml</code>.
  1763. This YAML file should contain a <code class="docutils literal">name</code> field for each image in the gallery
  1764. for which you wish to provide either a caption or specific ordering. You can also
  1765. create localized versions (<code class="docutils literal">metadata.xx.yml</code>).</p>
  1766. <p>Only one <code class="docutils literal">metadata.yml</code> is needed per gallery. Here is an example, showing names,
  1767. captions and ordering. <code class="docutils literal">caption</code> and <code class="docutils literal">order</code> are given special treatment,
  1768. anything else is available to templates, as keys of <code class="docutils literal">photo_array</code> images.</p>
  1769. <pre class="code yaml"><a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-1"></a><span class="nn">---</span>
  1770. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-2"></a><span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">ready-for-the-acid-wash.jpg</span>
  1771. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-3"></a><span class="nn">---</span>
  1772. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-4"></a><span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">almost-full.jpg</span>
  1773. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-5"></a><span class="nt">caption</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">The pool is now almost full</span>
  1774. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-6"></a><span class="nn">---</span>
  1775. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-7"></a><span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">jumping-in.jpg</span>
  1776. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-8"></a><span class="nt">caption</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">We&#39;re enjoying the new pool already</span>
  1777. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-9"></a><span class="nt">order</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">4</span>
  1778. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-10"></a><span class="nn">---</span>
  1779. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-11"></a><span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">waterline-tiles.jpg</span>
  1780. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-12"></a><span class="nt">order</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">2</span>
  1781. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-13"></a><span class="nt">custom</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">metadata is supported</span>
  1782. <a name="rest_code_a5ab5add4fc3486eabe3cdd5d1f61ead-14"></a><span class="nn">---</span>
  1783. </pre><p>Images to be used in normal posts can be placed in the <code class="docutils literal">images</code> folder. These
  1784. images will be processed and have thumbnails created just as for galleries, but will
  1785. then be copied directly to the corresponding path in the <code class="docutils literal">output</code> directory, so you
  1786. can reference it from whatever page you like, most easily using the <code class="docutils literal">thumbnail</code>
  1787. reST extension. If you don't want thumbnails, just use the <code class="docutils literal">files</code> folder instead.</p>
  1788. <p>The <code class="docutils literal">conf.py</code> options affecting images and gallery pages are these:</p>
  1789. <pre class="code python"><a name="rest_code_8805d8ef5320446780b0942becf47084-1"></a><span class="c1"># One or more folders containing galleries. The format is a dictionary of</span>
  1790. <a name="rest_code_8805d8ef5320446780b0942becf47084-2"></a><span class="c1"># {&quot;source&quot;: &quot;relative_destination&quot;}, where galleries are looked for in</span>
  1791. <a name="rest_code_8805d8ef5320446780b0942becf47084-3"></a><span class="c1"># &quot;source/&quot; and the results will be located in</span>
  1792. <a name="rest_code_8805d8ef5320446780b0942becf47084-4"></a><span class="c1"># &quot;OUTPUT_PATH/relative_destination/gallery_name&quot;</span>
  1793. <a name="rest_code_8805d8ef5320446780b0942becf47084-5"></a><span class="c1"># Default is:</span>
  1794. <a name="rest_code_8805d8ef5320446780b0942becf47084-6"></a><span class="n">GALLERY_FOLDERS</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;galleries&quot;</span><span class="p">:</span> <span class="s2">&quot;galleries&quot;</span><span class="p">}</span>
  1795. <a name="rest_code_8805d8ef5320446780b0942becf47084-7"></a><span class="c1"># More gallery options:</span>
  1796. <a name="rest_code_8805d8ef5320446780b0942becf47084-8"></a><span class="n">THUMBNAIL_SIZE</span> <span class="o">=</span> <span class="mi">180</span>
  1797. <a name="rest_code_8805d8ef5320446780b0942becf47084-9"></a><span class="n">MAX_IMAGE_SIZE</span> <span class="o">=</span> <span class="mi">1280</span>
  1798. <a name="rest_code_8805d8ef5320446780b0942becf47084-10"></a><span class="n">USE_FILENAME_AS_TITLE</span> <span class="o">=</span> <span class="kc">True</span>
  1799. <a name="rest_code_8805d8ef5320446780b0942becf47084-11"></a><span class="n">EXTRA_IMAGE_EXTENSIONS</span> <span class="o">=</span> <span class="p">[]</span>
  1800. <a name="rest_code_8805d8ef5320446780b0942becf47084-12"></a>
  1801. <a name="rest_code_8805d8ef5320446780b0942becf47084-13"></a><span class="c1"># Use a thumbnail (defined by &quot;.. previewimage:&quot; in the gallery&#39;s index) in</span>
  1802. <a name="rest_code_8805d8ef5320446780b0942becf47084-14"></a><span class="c1"># list of galleries for each gallery</span>
  1803. <a name="rest_code_8805d8ef5320446780b0942becf47084-15"></a><span class="n">GALLERIES_USE_THUMBNAIL</span> <span class="o">=</span> <span class="kc">False</span>
  1804. <a name="rest_code_8805d8ef5320446780b0942becf47084-16"></a>
  1805. <a name="rest_code_8805d8ef5320446780b0942becf47084-17"></a><span class="c1"># Image to use as thumbnail for those galleries that don&#39;t have one</span>
  1806. <a name="rest_code_8805d8ef5320446780b0942becf47084-18"></a><span class="c1"># None: show a grey square</span>
  1807. <a name="rest_code_8805d8ef5320446780b0942becf47084-19"></a><span class="c1"># &#39;/url/to/file&#39;: show the image in that url</span>
  1808. <a name="rest_code_8805d8ef5320446780b0942becf47084-20"></a><span class="n">GALLERIES_DEFAULT_THUMBNAIL</span> <span class="o">=</span> <span class="kc">None</span>
  1809. <a name="rest_code_8805d8ef5320446780b0942becf47084-21"></a>
  1810. <a name="rest_code_8805d8ef5320446780b0942becf47084-22"></a><span class="c1"># If set to False, it will sort by filename instead. Defaults to True</span>
  1811. <a name="rest_code_8805d8ef5320446780b0942becf47084-23"></a><span class="n">GALLERY_SORT_BY_DATE</span> <span class="o">=</span> <span class="kc">True</span>
  1812. <a name="rest_code_8805d8ef5320446780b0942becf47084-24"></a>
  1813. <a name="rest_code_8805d8ef5320446780b0942becf47084-25"></a><span class="c1"># Folders containing images to be used in normal posts or pages.</span>
  1814. <a name="rest_code_8805d8ef5320446780b0942becf47084-26"></a><span class="c1"># IMAGE_FOLDERS is a dictionary of the form {&quot;source&quot;: &quot;destination&quot;},</span>
  1815. <a name="rest_code_8805d8ef5320446780b0942becf47084-27"></a><span class="c1"># where &quot;source&quot; is the folder containing the images to be published, and</span>
  1816. <a name="rest_code_8805d8ef5320446780b0942becf47084-28"></a><span class="c1"># &quot;destination&quot; is the folder under OUTPUT_PATH containing the images copied</span>
  1817. <a name="rest_code_8805d8ef5320446780b0942becf47084-29"></a><span class="c1"># to the site. Thumbnail images will be created there as well.</span>
  1818. <a name="rest_code_8805d8ef5320446780b0942becf47084-30"></a><span class="n">IMAGE_FOLDERS</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;images&#39;</span><span class="p">:</span> <span class="s1">&#39;images&#39;</span><span class="p">}</span>
  1819. <a name="rest_code_8805d8ef5320446780b0942becf47084-31"></a>
  1820. <a name="rest_code_8805d8ef5320446780b0942becf47084-32"></a><span class="c1"># Images will be scaled down according to IMAGE_THUMBNAIL_SIZE and MAX_IMAGE_SIZE</span>
  1821. <a name="rest_code_8805d8ef5320446780b0942becf47084-33"></a><span class="c1"># options, but will have to be referenced manually to be visible on the site</span>
  1822. <a name="rest_code_8805d8ef5320446780b0942becf47084-34"></a><span class="c1"># (the thumbnail has ``.thumbnail`` added before the file extension by default,</span>
  1823. <a name="rest_code_8805d8ef5320446780b0942becf47084-35"></a><span class="c1"># but a different naming template can be configured with IMAGE_THUMBNAIL_FORMAT).</span>
  1824. <a name="rest_code_8805d8ef5320446780b0942becf47084-36"></a><span class="n">IMAGE_THUMBNAIL_SIZE</span> <span class="o">=</span> <span class="mi">400</span>
  1825. <a name="rest_code_8805d8ef5320446780b0942becf47084-37"></a><span class="n">IMAGE_THUMBNAIL_FORMAT</span> <span class="o">=</span> <span class="s1">&#39;</span><span class="si">{name}</span><span class="s1">.thumbnail</span><span class="si">{ext}</span><span class="s1">&#39;</span>
  1826. </pre><p>If you add a reST file in <code class="docutils literal">galleries/gallery_name/index.txt</code> its contents will be
  1827. converted to HTML and inserted above the images in the gallery page. The
  1828. format is the same as for posts. You can use the <code class="docutils literal">title</code>, <code class="docutils literal">previewimage</code>, and
  1829. <code class="docutils literal">status</code> metadata fields to change how the gallery is shown.</p>
  1830. <p>If the <code class="docutils literal">status</code> is <code class="docutils literal">private</code>, <code class="docutils literal">draft</code>, or <code class="docutils literal">publish_later</code>, the
  1831. gallery will not appear in the index, the RSS feeds, nor in the sitemap.</p>
  1832. <p>If you add some image filenames in <code class="docutils literal">galleries/gallery_name/exclude.meta</code>, they
  1833. will be excluded in the gallery page.</p>
  1834. <p>If <code class="docutils literal">USE_FILENAME_AS_TITLE</code> is True the filename (parsed as a readable string)
  1835. is used as the photo caption. If the filename starts with a number, it will
  1836. be stripped. For example <code class="docutils literal">03_an_amazing_sunrise.jpg</code> will be render as <em>An amazing sunrise</em>.</p>
  1837. <p>Here is a <a class="reference external" href="/galleries/demo">demo gallery</a> of historic, public domain Nikola
  1838. Tesla pictures taken from <a class="reference external" href="https://kerryr.net/pioneers/gallery/tesla.htm">this site</a>.</p>
  1839. <section id="embedding-images">
  1840. <h2><a class="toc-backref" href="#toc-entry-64" role="doc-backlink">Embedding Images</a></h2>
  1841. <p>Assuming that you have your pictures stored in a folder called <code class="docutils literal">images</code> (as configured above),
  1842. you can embed the same in your posts with the following reST directive:</p>
  1843. <pre class="code rest"><a name="rest_code_904428bd98e347cc9f0946216fcea184-1"></a><span class="p">..</span> <span class="ow">image</span><span class="p">::</span> /images/tesla.jpg
  1844. </pre><p>Which is equivalent to the following HTML code:</p>
  1845. <pre class="code html"><a name="rest_code_0fb93ef519964ad4a6c5c27cd7c444b6-1"></a><span class="p">&lt;</span><span class="nt">img</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;/images/tesla.jpg&quot;</span><span class="p">&gt;</span>
  1846. </pre><p>Please take note of the leading forward-slash <code class="docutils literal">/</code> which refers to the root
  1847. output directory. (Make sure to use this even if you’re not deploying to
  1848. web server root.)</p>
  1849. <p>You can also use thumbnails with the <code class="docutils literal">.. thumbnail::</code> reST directive. For
  1850. more details, and equivalent HTML code, see <a class="reference internal" href="#thumbnails">Thumbnails</a>.</p>
  1851. </section>
  1852. </section>
  1853. <section id="handling-exif-data">
  1854. <h1><a class="toc-backref" href="#toc-entry-65" role="doc-backlink">Handling EXIF Data</a></h1>
  1855. <p>Your images contain a certain amount of extra data besides the image itself,
  1856. called the <a class="reference external" href="https://en.wikipedia.org/wiki/Exchangeable_image_file_format">EXIF metadata.</a>
  1857. It contains information about the camera you used to take the picture, when it was taken,
  1858. and maybe even the location where it was taken.</p>
  1859. <p>This is both useful, because you can use it in some apps to locate all the pictures taken
  1860. in a certain place, or with a certain camera, but also, since the pictures Nikola
  1861. publishes are visible to anyone on the Internet, a privacy risk worth considering
  1862. (Imagine if you post pictures taken at home with GPS info, you are publishing your
  1863. home address!)</p>
  1864. <p>Nikola has some support for managing it, so let's go through a few scenarios to
  1865. see which one you prefer.</p>
  1866. <section id="strip-all-exif-data">
  1867. <h2><a class="toc-backref" href="#toc-entry-66" role="doc-backlink">Strip all EXIF data</a></h2>
  1868. <p>Do this if you want to be absolutely sure that no sensitive information should ever leak:</p>
  1869. <pre class="code python"><a name="rest_code_6a59dc109c2349f9b3f26058211d2f38-1"></a><span class="n">PRESERVE_EXIF_DATA</span> <span class="o">=</span> <span class="kc">False</span>
  1870. <a name="rest_code_6a59dc109c2349f9b3f26058211d2f38-2"></a><span class="n">EXIF_WHITELIST</span> <span class="o">=</span> <span class="p">{}</span>
  1871. </pre></section>
  1872. <section id="preserve-all-exif-data">
  1873. <h2><a class="toc-backref" href="#toc-entry-67" role="doc-backlink">Preserve all EXIF data</a></h2>
  1874. <p>Do this if you really don't mind people knowing where pictures were taken, or camera settings:</p>
  1875. <pre class="code python"><a name="rest_code_d1897f1f3c2348f89ea212ec4b07ee6b-1"></a><span class="n">PRESERVE_EXIF_DATA</span> <span class="o">=</span> <span class="kc">True</span>
  1876. <a name="rest_code_d1897f1f3c2348f89ea212ec4b07ee6b-2"></a><span class="n">EXIF_WHITELIST</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;*&#39;</span><span class="p">:</span> <span class="s1">&#39;*&#39;</span><span class="p">}</span>
  1877. </pre></section>
  1878. <section id="preserve-some-exif-data">
  1879. <h2><a class="toc-backref" href="#toc-entry-68" role="doc-backlink">Preserve some EXIF data</a></h2>
  1880. <p>Do this if you really know what you are doing. EXIF data comes separated in a few IFD blocks.
  1881. The most common ones are:</p>
  1882. <dl class="simple">
  1883. <dt>0th</dt>
  1884. <dd><p>Information about the image itself</p>
  1885. </dd>
  1886. <dt>Exif</dt>
  1887. <dd><p>Information about the camera and the image</p>
  1888. </dd>
  1889. <dt>1st</dt>
  1890. <dd><p>Information about embedded thumbnails (usually nothing)</p>
  1891. </dd>
  1892. <dt>thumbnail</dt>
  1893. <dd><p>An embedded thumbnail, in JPEG format (usually nothing)</p>
  1894. </dd>
  1895. <dt>GPS</dt>
  1896. <dd><p>Geolocation information about the image</p>
  1897. </dd>
  1898. <dt>Interop</dt>
  1899. <dd><p>Not too interesting at this point.</p>
  1900. </dd>
  1901. </dl>
  1902. <p>Each IFD in turn contains a number of tags. For example, 0th contains a ImageWidth tag.
  1903. You can tell Nikola exactly which IFDs to keep, and within each IFD, which tags to keep,
  1904. using the EXIF_WHITELIST option.</p>
  1905. <p>Let's see an example:</p>
  1906. <pre class="code python"><a name="rest_code_074d6b8c00034aa88655763ba6018095-1"></a><span class="n">PRESERVE_EXIF_DATA</span> <span class="o">=</span> <span class="kc">True</span>
  1907. <a name="rest_code_074d6b8c00034aa88655763ba6018095-2"></a><span class="n">EXIF_WHITELIST</span> <span class="o">=</span> <span class="p">{</span>
  1908. <a name="rest_code_074d6b8c00034aa88655763ba6018095-3"></a> <span class="s2">&quot;0th&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;Orientation&quot;</span><span class="p">,</span> <span class="s2">&quot;ImageWidth&quot;</span><span class="p">,</span> <span class="s2">&quot;ImageLength&quot;</span><span class="p">],</span>
  1909. <a name="rest_code_074d6b8c00034aa88655763ba6018095-4"></a> <span class="s2">&quot;Interop&quot;</span><span class="p">:</span> <span class="s2">&quot;*&quot;</span><span class="p">,</span>
  1910. <a name="rest_code_074d6b8c00034aa88655763ba6018095-5"></a><span class="p">}</span>
  1911. </pre><p>So, we preserve EXIF data, and the whitelisted IFDs are &quot;0th&quot; and &quot;Interop&quot;. That means
  1912. GPS, for example, will be totally deleted.</p>
  1913. <p>Then, for the Interop IFD, we keep everything, and for the 0th IFD we only keep three tags,
  1914. listed there.</p>
  1915. <p>There is a huge number of EXIF tags, described in <a class="reference external" href="http://www.cipa.jp/std/documents/e/DC-008-2012_E.pdf">the standard</a></p>
  1916. </section>
  1917. </section>
  1918. <section id="handling-icc-profiles">
  1919. <h1><a class="toc-backref" href="#toc-entry-69" role="doc-backlink">Handling ICC Profiles</a></h1>
  1920. <p>Your images may contain <a class="reference external" href="https://en.wikipedia.org/wiki/ICC_profile">ICC profiles.</a> These describe the color space in which the images were created or captured.</p>
  1921. <p>Most desktop web browsers can use embedded ICC profiles to display images accurately. As of early 2018 few mobile browsers consider ICC profiles when displaying images. A notable exception is Safari on iOS.</p>
  1922. <p>By default Nikola strips out ICC profiles when preparing images for your posts and galleries. If you want Nikola to preserve ICC profiles, add this in your <code class="docutils literal">conf.py</code>:</p>
  1923. <pre class="code python"><a name="rest_code_e6eaf766378841bbbc860d3b11122679-1"></a><span class="n">PRESERVE_ICC_PROFILES</span> <span class="o">=</span> <span class="kc">True</span>
  1924. </pre><p>You may wish to do this if, for example, your site contains JPEG images that use a wide-gamut profile such as &quot;Display P3&quot;.</p>
  1925. </section>
  1926. <section id="post-processing-filters">
  1927. <h1><a class="toc-backref" href="#toc-entry-70" role="doc-backlink">Post Processing Filters</a></h1>
  1928. <p>You can apply post processing to the files in your site, in order to optimize them
  1929. or change them in arbitrary ways. For example, you may want to compress all CSS
  1930. and JS files using yui-compressor.</p>
  1931. <p>To do that, you can use the provided helper adding this in your <code class="docutils literal">conf.py</code>:</p>
  1932. <pre class="code python"><a name="rest_code_42fbfa656d7046b1b4212f89ab8de86f-1"></a><span class="n">FILTERS</span> <span class="o">=</span> <span class="p">{</span>
  1933. <a name="rest_code_42fbfa656d7046b1b4212f89ab8de86f-2"></a> <span class="s2">&quot;.css&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;filters.yui_compressor&quot;</span><span class="p">],</span>
  1934. <a name="rest_code_42fbfa656d7046b1b4212f89ab8de86f-3"></a> <span class="s2">&quot;.js&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;filters.yui_compressor&quot;</span><span class="p">],</span>
  1935. <a name="rest_code_42fbfa656d7046b1b4212f89ab8de86f-4"></a><span class="p">}</span>
  1936. </pre><p>Where <code class="docutils literal">&quot;filters.yui_compressor&quot;</code> points to a helper function provided by Nikola in the
  1937. <code class="docutils literal">filters</code> module. You can replace that with strings describing command lines, or
  1938. arbitrary python functions.</p>
  1939. <p>If there's any specific thing you expect to be generally useful as a filter, contact
  1940. me and I will add it to the filters library so that more people use it.</p>
  1941. <p>The currently available filters are:</p>
  1942. <aside class="sidebar">
  1943. <p class="sidebar-title">Creating your own filters</p>
  1944. <p>You can use any program name that works in place as a filter, like <code class="docutils literal">sed <span class="pre">-i</span></code>
  1945. and you can use arbitrary Python functions as filters, too.</p>
  1946. <p>If your program doesn't run in-place, then you can use Nikola's <code class="docutils literal">runinplace</code> function (from the <code class="docutils literal">filters</code> module).
  1947. For example, this is how the yui_compressor filter is implemented:</p>
  1948. <pre class="code python"><a name="rest_code_24d77c8a82ff4e1893763213b8495827-1"></a><span class="kn">from</span> <span class="nn">nikola.filters</span> <span class="kn">import</span> <span class="n">runinplace</span>
  1949. <a name="rest_code_24d77c8a82ff4e1893763213b8495827-2"></a><span class="k">def</span> <span class="nf">yui_compressor</span><span class="p">(</span><span class="n">infile</span><span class="p">):</span>
  1950. <a name="rest_code_24d77c8a82ff4e1893763213b8495827-3"></a> <span class="k">return</span> <span class="n">runinplace</span><span class="p">(</span><span class="sa">r</span><span class="s1">&#39;yui-compressor --nomunge %1 -o %2&#39;</span><span class="p">,</span> <span class="n">infile</span><span class="p">)</span>
  1951. </pre><p>You can turn any function into a filter using <code class="docutils literal">apply_to_text_file</code> (for
  1952. text files to be read in UTF-8) and <code class="docutils literal">apply_to_binary_file</code> (for files to
  1953. be read in binary mode).</p>
  1954. <p>As a silly example, this would make everything uppercase and totally break
  1955. your website:</p>
  1956. <pre class="code python"><a name="rest_code_53c8543032bb404882fc332baf04c954-1"></a><span class="kn">import</span> <span class="nn">string</span>
  1957. <a name="rest_code_53c8543032bb404882fc332baf04c954-2"></a><span class="kn">from</span> <span class="nn">nikola.filters</span> <span class="kn">import</span> <span class="n">apply_to_text_file</span>
  1958. <a name="rest_code_53c8543032bb404882fc332baf04c954-3"></a><span class="n">FILTERS</span> <span class="o">=</span> <span class="p">{</span>
  1959. <a name="rest_code_53c8543032bb404882fc332baf04c954-4"></a> <span class="s2">&quot;.html&quot;</span><span class="p">:</span> <span class="p">[</span><span class="n">apply_to_text_file</span><span class="p">(</span><span class="n">string</span><span class="o">.</span><span class="n">upper</span><span class="p">)]</span>
  1960. <a name="rest_code_53c8543032bb404882fc332baf04c954-5"></a><span class="p">}</span>
  1961. </pre></aside>
  1962. <dl>
  1963. <dt>filters.html_tidy_nowrap</dt>
  1964. <dd><p>Prettify HTML 5 documents with <a class="reference external" href="https://www.html-tidy.org/">tidy5</a></p>
  1965. </dd>
  1966. <dt>filters.html_tidy_wrap</dt>
  1967. <dd><p>Prettify HTML 5 documents wrapped at 80 characters with <a class="reference external" href="https://www.html-tidy.org/">tidy5</a></p>
  1968. </dd>
  1969. <dt>filters.html_tidy_wrap_attr</dt>
  1970. <dd><p>Prettify HTML 5 documents and wrap lines and attributes with <a class="reference external" href="https://www.html-tidy.org/">tidy5</a></p>
  1971. </dd>
  1972. <dt>filters.html_tidy_mini</dt>
  1973. <dd><p>Minify HTML 5 into smaller documents with <a class="reference external" href="https://www.html-tidy.org/">tidy5</a></p>
  1974. </dd>
  1975. <dt>filters.html_tidy_withconfig</dt>
  1976. <dd><p>Run <a class="reference external" href="https://www.html-tidy.org/">tidy5</a> with <code class="docutils literal">tidy5.conf</code> as the config file (supplied by user)</p>
  1977. </dd>
  1978. <dt>filters.html5lib_minify</dt>
  1979. <dd><p>Minify HTML5 using html5lib_minify</p>
  1980. </dd>
  1981. <dt>filters.html5lib_xmllike</dt>
  1982. <dd><p>Format using html5lib</p>
  1983. </dd>
  1984. <dt>filters.typogrify</dt>
  1985. <dd><p>Improve typography using <a class="reference external" href="https://github.com/mintchaos/typogrify">typogrify</a></p>
  1986. </dd>
  1987. <dt>filters.typogrify_sans_widont</dt>
  1988. <dd><p>Same as typogrify without the widont filter</p>
  1989. </dd>
  1990. <dt>filters.typogrify_custom</dt>
  1991. <dd><p>Run typogrify with a custom set of filters or ignored HTML elements. Takes one or
  1992. both of the arguments <code class="docutils literal">typogrify_filters</code> or <code class="docutils literal">ignore_tags</code>. <code class="docutils literal">typogrify_filters</code>
  1993. must be a list of typogrify filter callables to run. <code class="docutils literal">ignore_tags</code> must be a list
  1994. of strings specifying HTML tags, CSS classes (prefixed with <code class="docutils literal">.</code>), tag <code class="docutils literal">id</code> names
  1995. (prefixed with <code class="docutils literal">#</code>), or a tag and a class or id. The following code should be
  1996. placed in <code class="docutils literal">conf.py</code>.</p>
  1997. <pre class="code python"><a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-1"></a><span class="kn">from</span> <span class="nn">nikola.filters</span> <span class="kn">import</span> <span class="n">typogrify_custom</span>
  1998. <a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-2"></a><span class="kn">import</span> <span class="nn">functools</span>
  1999. <a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-3"></a><span class="c1"># This filter will ignore HTML elements with the CSS class &quot;typo-ignore&quot;</span>
  2000. <a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-4"></a><span class="n">FILTERS</span> <span class="o">=</span> <span class="p">{</span>
  2001. <a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-5"></a> <span class="s2">&quot;.html&quot;</span><span class="p">:</span> <span class="p">[</span><span class="n">functools</span><span class="o">.</span><span class="n">partial</span><span class="p">(</span><span class="n">typogrify_custom</span><span class="p">,</span> <span class="n">ignore_tags</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;.typo-ignore&quot;</span><span class="p">])]</span>
  2002. <a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-6"></a><span class="p">}</span>
  2003. <a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-7"></a><span class="c1"># Alternatively, to specify ``typogrify_filters``</span>
  2004. <a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-8"></a><span class="kn">import</span> <span class="nn">typogrify.filters</span> <span class="k">as</span> <span class="nn">typo</span>
  2005. <a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-9"></a><span class="n">FILTERS</span> <span class="o">=</span> <span class="p">{</span>
  2006. <a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-10"></a> <span class="s2">&quot;.html&quot;</span><span class="p">:</span> <span class="p">[</span><span class="n">functools</span><span class="o">.</span><span class="n">partial</span><span class="p">(</span><span class="n">typogrify_custom</span><span class="p">,</span> <span class="n">typogrify_filters</span><span class="o">=</span><span class="p">[</span><span class="n">typo</span><span class="o">.</span><span class="n">amp</span><span class="p">])]</span>
  2007. <a name="rest_code_cff929451ecd4fadacb070fa7e63e5a6-11"></a><span class="p">}</span>
  2008. </pre><p>The default value for <code class="docutils literal">typogrify_filters</code> is
  2009. <code class="docutils literal">[typo.amp, typo.widont, typo.smartypants, typo.caps, typo.initial_quotes]</code> and the
  2010. default value for <code class="docutils literal">ignore_tags</code> is <code class="docutils literal">[&quot;title&quot;, &quot;.math&quot;]</code>. If <code class="docutils literal">ignore_tags</code> is
  2011. specified, the default tags will be appended to the supplied list. See the
  2012. <a class="reference external" href="https://github.com/mintchaos/typogrify/blob/master/typogrify/filters.py#L8-L14">documentation</a>
  2013. for the <code class="docutils literal">process_ignores</code> function in typogrify.</p>
  2014. </dd>
  2015. <dt>filters.minify_lines</dt>
  2016. <dd><p><strong>THIS FILTER HAS BEEN TURNED INTO A NOOP</strong> and currently does nothing.</p>
  2017. </dd>
  2018. <dt>filters.normalize_html</dt>
  2019. <dd><p>Pass HTML through LXML to normalize it. For example, it will resolve <code class="docutils literal">&amp;quot;</code> to actual
  2020. quotes. Usually not needed.</p>
  2021. </dd>
  2022. <dt>filters.yui_compressor</dt>
  2023. <dd><p>Compress CSS/JavaScript using <a class="reference external" href="https://yui.github.io/yuicompressor/">YUI compressor</a></p>
  2024. </dd>
  2025. <dt>filters.closure_compiler</dt>
  2026. <dd><p>Compile, compress, and optimize JavaScript <a class="reference external" href="https://developers.google.com/closure/compiler/">Google Closure Compiler</a></p>
  2027. </dd>
  2028. <dt>filters.optipng</dt>
  2029. <dd><p>Compress PNG files using <a class="reference external" href="http://optipng.sourceforge.net/">optipng</a></p>
  2030. </dd>
  2031. <dt>filters.jpegoptim</dt>
  2032. <dd><p>Compress JPEG files using <a class="reference external" href="https://www.kokkonen.net/tjko/projects.html">jpegoptim</a></p>
  2033. </dd>
  2034. <dt>filters.cssminify</dt>
  2035. <dd><p>Minify CSS using <a class="reference external" href="https://cssminifier.com/">https://cssminifier.com/</a> (requires Internet access)</p>
  2036. </dd>
  2037. <dt>filters.jsminify</dt>
  2038. <dd><p>Minify JS using <a class="reference external" href="https://javascript-minifier.com/">https://javascript-minifier.com/</a> (requires Internet access)</p>
  2039. </dd>
  2040. <dt>filters.jsonminify</dt>
  2041. <dd><p>Minify JSON files (strip whitespace and use minimal separators).</p>
  2042. </dd>
  2043. <dt>filters.xmlminify</dt>
  2044. <dd><p>Minify XML files. Suitable for Nikola’s sitemaps and Atom feeds.</p>
  2045. </dd>
  2046. <dt>filters.add_header_permalinks</dt>
  2047. <dd><p>Add links next to every header, Sphinx-style. You will need to add styling for the <cite>headerlink</cite> class,
  2048. in <cite>custom.css</cite>, for example:</p>
  2049. <pre class="code css"><a name="rest_code_23a0b8e4e225420e91637d0a55452b18-1"></a><span class="c">/* Header permalinks */</span>
  2050. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-2"></a><span class="nt">h1</span><span class="p">:</span><span class="nd">hover</span> <span class="p">.</span><span class="nc">headerlink</span><span class="o">,</span> <span class="nt">h2</span><span class="p">:</span><span class="nd">hover</span> <span class="p">.</span><span class="nc">headerlink</span><span class="o">,</span>
  2051. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-3"></a><span class="nt">h3</span><span class="p">:</span><span class="nd">hover</span> <span class="p">.</span><span class="nc">headerlink</span><span class="o">,</span> <span class="nt">h4</span><span class="p">:</span><span class="nd">hover</span> <span class="p">.</span><span class="nc">headerlink</span><span class="o">,</span>
  2052. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-4"></a><span class="nt">h5</span><span class="p">:</span><span class="nd">hover</span> <span class="p">.</span><span class="nc">headerlink</span><span class="o">,</span> <span class="nt">h6</span><span class="p">:</span><span class="nd">hover</span> <span class="p">.</span><span class="nc">headerlink</span> <span class="p">{</span>
  2053. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-5"></a> <span class="k">display</span><span class="p">:</span> <span class="kc">inline</span><span class="p">;</span>
  2054. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-6"></a><span class="p">}</span>
  2055. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-7"></a>
  2056. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-8"></a><span class="p">.</span><span class="nc">headerlink</span> <span class="p">{</span>
  2057. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-9"></a> <span class="k">display</span><span class="p">:</span> <span class="kc">none</span><span class="p">;</span>
  2058. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-10"></a> <span class="k">color</span><span class="p">:</span> <span class="mh">#ddd</span><span class="p">;</span>
  2059. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-11"></a> <span class="k">margin-left</span><span class="p">:</span> <span class="mf">0.2</span><span class="kt">em</span><span class="p">;</span>
  2060. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-12"></a> <span class="k">padding</span><span class="p">:</span> <span class="mi">0</span> <span class="mf">0.2</span><span class="kt">em</span><span class="p">;</span>
  2061. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-13"></a><span class="p">}</span>
  2062. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-14"></a>
  2063. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-15"></a><span class="p">.</span><span class="nc">headerlink</span><span class="p">:</span><span class="nd">hover</span> <span class="p">{</span>
  2064. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-16"></a> <span class="k">opacity</span><span class="p">:</span> <span class="mi">1</span><span class="p">;</span>
  2065. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-17"></a> <span class="k">background</span><span class="p">:</span> <span class="mh">#ddd</span><span class="p">;</span>
  2066. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-18"></a> <span class="k">color</span><span class="p">:</span> <span class="mh">#000</span><span class="p">;</span>
  2067. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-19"></a> <span class="k">text-decoration</span><span class="p">:</span> <span class="kc">none</span><span class="p">;</span>
  2068. <a name="rest_code_23a0b8e4e225420e91637d0a55452b18-20"></a><span class="p">}</span>
  2069. </pre><p>Additionally, you can provide a custom list of XPath expressions which should be used for finding headers (<code class="docutils literal">{hx}</code> is replaced by headers h1 through h6).
  2070. This is required if you use a custom theme that does not use <code class="docutils literal"><span class="pre">&quot;e-content</span> <span class="pre">entry-content&quot;</span></code> as a class for post and page contents.</p>
  2071. <pre class="code python"><a name="rest_code_aee967f647e14195b882cad72e443193-1"></a><span class="c1"># Default value:</span>
  2072. <a name="rest_code_aee967f647e14195b882cad72e443193-2"></a><span class="n">HEADER_PERMALINKS_XPATH_LIST</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;*//div[@class=&quot;e-content entry-content&quot;]//</span><span class="si">{hx}</span><span class="s1">&#39;</span><span class="p">]</span>
  2073. <a name="rest_code_aee967f647e14195b882cad72e443193-3"></a><span class="c1"># Include *every* header (not recommended):</span>
  2074. <a name="rest_code_aee967f647e14195b882cad72e443193-4"></a><span class="c1"># HEADER_PERMALINKS_XPATH_LIST = [&#39;*//{hx}&#39;]</span>
  2075. </pre></dd>
  2076. <dt>filters.deduplicate_ids</dt>
  2077. <dd><p>Prevent duplicated IDs in HTML output. An incrementing counter is added to
  2078. offending IDs. If used alongside <code class="docutils literal">add_header_permalinks</code>, it will fix
  2079. those links (it must run <strong>after</strong> that filter)</p>
  2080. <p>IDs are numbered from the bottom up, which is useful for indexes (updates
  2081. appear at the top). There are exceptions, which may be configured using
  2082. <code class="docutils literal">DEDUPLICATE_IDS_TOP_CLASSES</code> — if any of those classes appears sin the
  2083. document, the IDs are rewritten top-down, which is useful for posts/pages
  2084. (updates appear at the bottom).</p>
  2085. <p>Note that in rare cases, permalinks might not always be <em>permanent</em> in case
  2086. of edits.</p>
  2087. <pre class="code python"><a name="rest_code_e4306ecfa4134588874b554eeb9aa7f1-1"></a><span class="n">DEDUPLICATE_IDS_TOP_CLASSES</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;postpage&#39;</span><span class="p">,</span> <span class="s1">&#39;storypage&#39;</span><span class="p">)</span>
  2088. </pre><p>You can also use a file blacklist (<code class="docutils literal">HEADER_PERMALINKS_FILE_BLACKLIST</code>),
  2089. useful for some index pages. Paths include the output directory (eg.
  2090. <code class="docutils literal">output/index.html</code>)</p>
  2091. </dd>
  2092. </dl>
  2093. <p>You can apply filters to specific posts or pages by using the <code class="docutils literal">filters</code> metadata field:</p>
  2094. <pre class="code restructuredtext"><a name="rest_code_a5571e38ee544cccaa8110629a6778fb-1"></a><span class="cp">.. filters: filters.html_tidy_nowrap, &quot;sed s/foo/bar %s&quot;</span>
  2095. </pre><p>Please note that applying custom filters (not those provided via Nikola's filter module)
  2096. via metadata only works for filters implemented via external programs like in that <cite>sed</cite> example.</p>
  2097. </section>
  2098. <section id="optimizing-your-website">
  2099. <h1><a class="toc-backref" href="#toc-entry-71" role="doc-backlink">Optimizing Your Website</a></h1>
  2100. <p>One of the main goals of Nikola is to make your site fast and light. So here are a few
  2101. tips we have found when setting up Nikola with Apache. If you have more, or
  2102. different ones, or about other web servers, please share!</p>
  2103. <ol class="arabic">
  2104. <li><p>Use a speed testing tool. I used Yahoo's YSlow but you can use any of them, and
  2105. it's probably a good idea to use more than one.</p></li>
  2106. <li><p>Enable compression in Apache:</p>
  2107. <pre class="code apache"><a name="rest_code_5264f69fd10443d7b15ff2e58cba557b-1"></a><span class="nb">AddOutputFilterByType</span> DEFLATE text/html text/plain text/xml text/css text/javascript
  2108. </pre></li>
  2109. <li><p>If even after you did the previous step the CSS files are not sent compressed:</p>
  2110. <pre class="code apache"><a name="rest_code_35580c9bfd29414aa75d002cc8b6dd19-1"></a><span class="nb">AddType</span> text/css .css
  2111. </pre></li>
  2112. <li><p>Optionally you can create static compressed copies and save some CPU on your server
  2113. with the GZIP_FILES option in Nikola.</p></li>
  2114. <li><p>The bundles Nikola plugin can drastically decrease the number of CSS and JS files your site fetches.</p></li>
  2115. <li><p>Through the filters feature, you can run your files through arbitrary commands, so that images
  2116. are recompressed, JavaScript is minimized, etc.</p></li>
  2117. <li><p>The USE_CDN option offloads standard JavaScript and CSS files to a CDN so they are not
  2118. downloaded from your server.</p></li>
  2119. </ol>
  2120. </section>
  2121. <section id="math">
  2122. <h1><a class="toc-backref" href="#toc-entry-72" role="doc-backlink">Math</a></h1>
  2123. <p>Nikola supports math input via MathJax (by default) or KaTeX. It is activated
  2124. via the math roles and directives of reStructuredText and the usual LaTeX
  2125. delimiters for other input formats.</p>
  2126. <section id="configuration-1">
  2127. <h2><a class="toc-backref" href="#toc-entry-73" role="doc-backlink">Configuration</a></h2>
  2128. <p>Nikola uses MathJax by default. If you want to use KaTeX (faster and prettier,
  2129. but may not support every feature yet), set <code class="docutils literal">USE_KATEX = True</code> in
  2130. <code class="docutils literal">conf.py</code>.</p>
  2131. <p>To use mathematics in a post, you <strong>must</strong> set the <code class="docutils literal">has_math</code> metadata field
  2132. to <code class="docutils literal">true</code>. (Exception: posts that are Jupyter Notebooks are automatically
  2133. marked as math)</p>
  2134. <!-- Note to editors: the paragraph below uses U+200B, zero-width space. Don’t break it. -->
  2135. <p>By default, Nikola will accept <code class="docutils literal"><span class="pre">\​(...\​)</span></code> for inline math; <code class="docutils literal"><span class="pre">\​[...\​]</span></code> and
  2136. <code class="docutils literal"><span class="pre">$​$...$​$</span></code> for display math. If you want to use the old <code class="docutils literal"><span class="pre">$...$</span></code> syntax as well
  2137. (which may conflict with running text!), you need to use special config for
  2138. your renderer:</p>
  2139. <pre class="code python"><a name="rest_code_29a2de419c9648389ff48384089335bd-1"></a><span class="n">MATHJAX_CONFIG</span> <span class="o">=</span> <span class="s2">&quot;&quot;&quot;</span>
  2140. <a name="rest_code_29a2de419c9648389ff48384089335bd-2"></a><span class="s2">&lt;script type=&quot;text/x-mathjax-config&quot;&gt;</span>
  2141. <a name="rest_code_29a2de419c9648389ff48384089335bd-3"></a><span class="s2">MathJax.Hub.Config({</span>
  2142. <a name="rest_code_29a2de419c9648389ff48384089335bd-4"></a><span class="s2"> tex2jax: {</span>
  2143. <a name="rest_code_29a2de419c9648389ff48384089335bd-5"></a><span class="s2"> inlineMath: [ [&#39;$&#39;,&#39;$&#39;], [&quot;</span><span class="se">\\</span><span class="s2">\(&quot;,&quot;</span><span class="se">\\</span><span class="s2">\)&quot;] ],</span>
  2144. <a name="rest_code_29a2de419c9648389ff48384089335bd-6"></a><span class="s2"> displayMath: [ [&#39;$$&#39;,&#39;$$&#39;], [&quot;</span><span class="se">\\</span><span class="s2">\[&quot;,&quot;</span><span class="se">\\</span><span class="s2">\]&quot;] ],</span>
  2145. <a name="rest_code_29a2de419c9648389ff48384089335bd-7"></a><span class="s2"> processEscapes: true</span>
  2146. <a name="rest_code_29a2de419c9648389ff48384089335bd-8"></a><span class="s2"> },</span>
  2147. <a name="rest_code_29a2de419c9648389ff48384089335bd-9"></a><span class="s2"> displayAlign: &#39;center&#39;, // Change this to &#39;left&#39; if you want left-aligned equations.</span>
  2148. <a name="rest_code_29a2de419c9648389ff48384089335bd-10"></a><span class="s2"> &quot;HTML-CSS&quot;: {</span>
  2149. <a name="rest_code_29a2de419c9648389ff48384089335bd-11"></a><span class="s2"> styles: {&#39;.MathJax_Display&#39;: {&quot;margin&quot;: 0}}</span>
  2150. <a name="rest_code_29a2de419c9648389ff48384089335bd-12"></a><span class="s2"> }</span>
  2151. <a name="rest_code_29a2de419c9648389ff48384089335bd-13"></a><span class="s2">});</span>
  2152. <a name="rest_code_29a2de419c9648389ff48384089335bd-14"></a><span class="s2">&lt;/script&gt;</span>
  2153. <a name="rest_code_29a2de419c9648389ff48384089335bd-15"></a><span class="s2">&quot;&quot;&quot;</span>
  2154. <a name="rest_code_29a2de419c9648389ff48384089335bd-16"></a>
  2155. <a name="rest_code_29a2de419c9648389ff48384089335bd-17"></a><span class="n">KATEX_AUTO_RENDER</span> <span class="o">=</span> <span class="s2">&quot;&quot;&quot;</span>
  2156. <a name="rest_code_29a2de419c9648389ff48384089335bd-18"></a><span class="s2">delimiters: [</span>
  2157. <a name="rest_code_29a2de419c9648389ff48384089335bd-19"></a><span class="s2"> {left: &quot;$$&quot;, right: &quot;$$&quot;, display: true},</span>
  2158. <a name="rest_code_29a2de419c9648389ff48384089335bd-20"></a><span class="s2"> {left: &quot;</span><span class="se">\\</span><span class="s2">\[&quot;, right: &quot;</span><span class="se">\\</span><span class="s2">\]&quot;, display: true},</span>
  2159. <a name="rest_code_29a2de419c9648389ff48384089335bd-21"></a><span class="s2"> {left: &quot;$&quot;, right: &quot;$&quot;, display: false},</span>
  2160. <a name="rest_code_29a2de419c9648389ff48384089335bd-22"></a><span class="s2"> {left: &quot;</span><span class="se">\\</span><span class="s2">\(&quot;, right: &quot;</span><span class="se">\\</span><span class="s2">\)&quot;, display: false}</span>
  2161. <a name="rest_code_29a2de419c9648389ff48384089335bd-23"></a><span class="s2">]</span>
  2162. <a name="rest_code_29a2de419c9648389ff48384089335bd-24"></a><span class="s2">&quot;&quot;&quot;</span>
  2163. </pre><p><em>(Note: the previous paragraph uses invisible characters to prevent rendering
  2164. TeX for display, so don’t copy the examples with three dots to your posts)</em></p>
  2165. </section>
  2166. <section id="inline-usage">
  2167. <h2><a class="toc-backref" href="#toc-entry-74" role="doc-backlink">Inline usage</a></h2>
  2168. <p>Inline mathematics are produced using the reST <cite>math</cite> <strong>role</strong> or the LaTeX
  2169. backslash-parentheses delimiters:</p>
  2170. <p>Euler’s formula: <span class="math">\(e^{ix} = \cos x + i\sin x\)</span></p>
  2171. <p>In reST:</p>
  2172. <pre class="code restructuredtext"><a name="rest_code_393ebc4ee6a64b4ca93decd5ea3c6d65-1"></a>Euler’s formula: <span class="na">:math:</span><span class="nv">`e^{ix} = \cos x + i\sin x`</span>
  2173. </pre><p>In HTML and other input formats:</p>
  2174. <pre class="code text"><a name="rest_code_19376130ec434673a2686d863af80f81-1"></a>Euler’s formula: \(e^{ix} = \cos x + i\sin x\)
  2175. </pre><p>Note that some input formats (including Markdown) require using <strong>double
  2176. backslashes</strong> in the delimiters (<code class="docutils literal"><span class="pre">\\(inline</span> <span class="pre">math\\)</span></code>). Please check your
  2177. output first before reporting bugs.</p>
  2178. </section>
  2179. <section id="display-usage">
  2180. <h2><a class="toc-backref" href="#toc-entry-75" role="doc-backlink">Display usage</a></h2>
  2181. <p>Display mathematics are produced using the reST <cite>math</cite> <strong>directive</strong> or the
  2182. LaTeX backslash-brackets delimiters:</p>
  2183. <div class="math">
  2184. \begin{equation*}
  2185. \int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C
  2186. \end{equation*}
  2187. </div>
  2188. <p>In reST:</p>
  2189. <pre class="code restructuredtext"><a name="rest_code_88948d9bd8b54c61a22e272d07beea37-1"></a><span class="p">..</span> <span class="ow">math</span><span class="p">::</span>
  2190. <a name="rest_code_88948d9bd8b54c61a22e272d07beea37-2"></a>
  2191. <a name="rest_code_88948d9bd8b54c61a22e272d07beea37-3"></a> \int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C
  2192. </pre><p>In HTML and other input formats:</p>
  2193. <pre class="code text"><a name="rest_code_7373f5fae80e40eaab5a3acb15d8c46d-1"></a>\[\int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C\]
  2194. </pre><p>Note that some input formats (including Markdown) require using <strong>double
  2195. backslashes</strong> in the delimiters (<code class="docutils literal"><span class="pre">\\[display</span> <span class="pre">math\\]</span></code>). Please check your
  2196. output first before reporting bugs.</p>
  2197. </section>
  2198. </section>
  2199. <section id="restructuredtext-extensions">
  2200. <h1><a class="toc-backref" href="#toc-entry-76" role="doc-backlink">reStructuredText Extensions</a></h1>
  2201. <p>Nikola includes support for a few directives and roles that are not part of docutils, but which
  2202. we think are handy for website development.</p>
  2203. <section id="includes">
  2204. <h2><a class="toc-backref" href="#toc-entry-77" role="doc-backlink">Includes</a></h2>
  2205. <p>Nikola supports the standard reStructuredText <code class="docutils literal">include</code> directive, but with a
  2206. catch: filenames are relative to <strong>Nikola site root</strong> (directory with <code class="docutils literal">conf.py</code>)
  2207. instead of the post location (eg. <code class="docutils literal">posts/</code> directory)!</p>
  2208. </section>
  2209. <section id="media">
  2210. <h2><a class="toc-backref" href="#toc-entry-78" role="doc-backlink">Media</a></h2>
  2211. <p>This directive lets you embed media from a variety of sites automatically by just passing the
  2212. URL of the page. For example here are two random videos:</p>
  2213. <pre class="code restructuredtext"><a name="rest_code_f6d1a5d2b5de4fe9b25f343315effd28-1"></a><span class="p">..</span> <span class="ow">media</span><span class="p">::</span> https://vimeo.com/72425090
  2214. <a name="rest_code_f6d1a5d2b5de4fe9b25f343315effd28-2"></a>
  2215. <a name="rest_code_f6d1a5d2b5de4fe9b25f343315effd28-3"></a><span class="p">..</span> <span class="ow">media</span><span class="p">::</span> https://www.youtube.com/watch?v=wyRpAat5oz0
  2216. </pre><p>It supports Instagram, Flickr, Github gists, Funny or Die, and dozens more, thanks to <a class="reference external" href="https://github.com/coleifer/micawber">Micawber</a></p>
  2217. </section>
  2218. <section id="youtube">
  2219. <h2><a class="toc-backref" href="#toc-entry-79" role="doc-backlink">YouTube</a></h2>
  2220. <p>To link to a YouTube video, you need the id of the video. For example, if the
  2221. URL of the video is <a class="reference external" href="https://www.youtube.com/watch?v=8N_tupPBtWQ">https://www.youtube.com/watch?v=8N_tupPBtWQ</a> what you need is
  2222. <strong>8N_tupPBtWQ</strong></p>
  2223. <p>Once you have that, all you need to do is:</p>
  2224. <pre class="code restructuredtext"><a name="rest_code_d65e6dc2b9794988ba0a7b4d59a895e5-1"></a><span class="p">..</span> <span class="ow">youtube</span><span class="p">::</span> 8N_tupPBtWQ
  2225. </pre><p>Supported options: <code class="docutils literal">height</code>, <code class="docutils literal">width</code>, <code class="docutils literal">start_at</code>, <code class="docutils literal">align</code> (one of <code class="docutils literal">left</code>,
  2226. <code class="docutils literal">center</code>, <code class="docutils literal">right</code>) — all are optional. Example:</p>
  2227. <pre class="code restructuredtext"><a name="rest_code_5994c24194594903af696e19e15a8ff1-1"></a><span class="p">..</span> <span class="ow">youtube</span><span class="p">::</span> 8N_tupPBtWQ
  2228. <a name="rest_code_5994c24194594903af696e19e15a8ff1-2"></a> <span class="nc">:align:</span> center
  2229. <a name="rest_code_5994c24194594903af696e19e15a8ff1-3"></a> <span class="nc">:start_at:</span> 4
  2230. </pre></section>
  2231. <section id="vimeo">
  2232. <h2><a class="toc-backref" href="#toc-entry-80" role="doc-backlink">Vimeo</a></h2>
  2233. <p>To link to a Vimeo video, you need the id of the video. For example, if the
  2234. URL of the video is <a class="reference external" href="https://vimeo.com/20241459">https://vimeo.com/20241459</a> then the id is <strong>20241459</strong></p>
  2235. <p>Once you have that, all you need to do is:</p>
  2236. <pre class="code restructuredtext"><a name="rest_code_9d22c96b9dc94462ae3e2c3dcb120133-1"></a><span class="p">..</span> <span class="ow">vimeo</span><span class="p">::</span> 20241459
  2237. </pre><p>If you have internet connectivity when generating your site, the height and width of
  2238. the embedded player will be set to the native height and width of the video.
  2239. You can override this if you wish:</p>
  2240. <pre class="code restructuredtext"><a name="rest_code_e750474411fd41399d4465d25eef43da-1"></a><span class="p">..</span> <span class="ow">vimeo</span><span class="p">::</span> 20241459
  2241. <a name="rest_code_e750474411fd41399d4465d25eef43da-2"></a> <span class="nc">:height:</span> 240
  2242. <a name="rest_code_e750474411fd41399d4465d25eef43da-3"></a> <span class="nc">:width:</span> 320
  2243. </pre><p>Supported options: <code class="docutils literal">height</code>, <code class="docutils literal">width</code>, <code class="docutils literal">align</code> (one of <code class="docutils literal">left</code>,
  2244. <code class="docutils literal">center</code>, <code class="docutils literal">right</code>) — all are optional.</p>
  2245. </section>
  2246. <section id="soundcloud">
  2247. <h2><a class="toc-backref" href="#toc-entry-81" role="doc-backlink">Soundcloud</a></h2>
  2248. <p>This directive lets you share music from <a class="reference external" href="https://soundcloud.com">https://soundcloud.com</a> You first need to get the
  2249. ID for the piece, which you can find in the &quot;share&quot; link. For example, if the
  2250. WordPress code starts like this:</p>
  2251. <pre class="code text"><a name="rest_code_16d563c463994e79bf7433a77969079e-1"></a>[soundcloud url=&quot;http://api.soundcloud.com/tracks/78131362&quot; …/]
  2252. </pre><p>The ID is 78131362 and you can embed the audio with this:</p>
  2253. <pre class="code restructuredtext"><a name="rest_code_e628736d7cfd425eac28cc78532e9f7e-1"></a><span class="p">..</span> <span class="ow">soundcloud</span><span class="p">::</span> 78131362
  2254. </pre><p>You can also embed playlists, via the <cite>soundcloud_playlist</cite> directive which works the same way.</p>
  2255. <blockquote>
  2256. <div class="soundcloud-player">
  2257. <iframe width="600" height="160"
  2258. scrolling="no" frameborder="no"
  2259. src="https://w.soundcloud.com/player/?url=http://api.soundcloud.com/playlists/9411706">
  2260. </iframe>
  2261. </div></blockquote>
  2262. <p>Supported options: <code class="docutils literal">height</code>, <code class="docutils literal">width</code>, <code class="docutils literal">align</code> (one of <code class="docutils literal">left</code>,
  2263. <code class="docutils literal">center</code>, <code class="docutils literal">right</code>) — all are optional.</p>
  2264. </section>
  2265. <section id="code">
  2266. <h2><a class="toc-backref" href="#toc-entry-82" role="doc-backlink">Code</a></h2>
  2267. <p>The <code class="docutils literal">code</code> directive has been included in docutils since version 0.9 and now
  2268. replaces Nikola's <code class="docutils literal"><span class="pre">code-block</span></code> directive. To ease the transition, two aliases
  2269. for <code class="docutils literal">code</code> directive are provided: <code class="docutils literal"><span class="pre">code-block</span></code> and <code class="docutils literal">sourcecode</code>:</p>
  2270. <pre class="code restructuredtext"><a name="rest_code_51f5562a23bc486d8d9af238e5a1990d-1"></a><span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> python
  2271. <a name="rest_code_51f5562a23bc486d8d9af238e5a1990d-2"></a> <span class="nc">:number-lines:</span>
  2272. <a name="rest_code_51f5562a23bc486d8d9af238e5a1990d-3"></a>
  2273. <a name="rest_code_51f5562a23bc486d8d9af238e5a1990d-4"></a> print(&quot;Our virtues and our failings are inseparable&quot;)
  2274. </pre><p>Certain lines might be highlighted via the <code class="docutils literal"><span class="pre">emphasize-lines</span></code> directive:</p>
  2275. <pre class="code restructuredtext"><a name="rest_code_011532fe246d403689684094a3044cc0-1"></a><span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> python
  2276. <a name="rest_code_011532fe246d403689684094a3044cc0-2"></a> <span class="nc">:emphasize-lines:</span> 3,5
  2277. <a name="rest_code_011532fe246d403689684094a3044cc0-3"></a>
  2278. <a name="rest_code_011532fe246d403689684094a3044cc0-4"></a> def some_function():
  2279. <a name="rest_code_011532fe246d403689684094a3044cc0-5"></a> interesting = False
  2280. <a name="rest_code_011532fe246d403689684094a3044cc0-6"></a> print(&#39;This line is highlighted.&#39;)
  2281. <a name="rest_code_011532fe246d403689684094a3044cc0-7"></a> print(&#39;This one is not...&#39;)
  2282. <a name="rest_code_011532fe246d403689684094a3044cc0-8"></a> print(&#39;...but this one is.&#39;)
  2283. </pre><p>Line ranges are also supported, such as <code class="docutils literal"><span class="pre">:emphasize-lines:</span> <span class="pre">1-3,5-9,15</span></code>.</p>
  2284. </section>
  2285. <section id="listing">
  2286. <h2><a class="toc-backref" href="#toc-entry-83" role="doc-backlink">Listing</a></h2>
  2287. <p>To use this, you have to put your source code files inside <code class="docutils literal">listings</code> or whatever folders
  2288. your <code class="docutils literal">LISTINGS_FOLDERS</code> variable is set to fetch files from. Assuming you have a <code class="docutils literal">foo.py</code>
  2289. inside one of these folders:</p>
  2290. <pre class="code restructuredtext"><a name="rest_code_0489c4bbfd8243f186eb2cf25a781062-1"></a><span class="p">..</span> <span class="ow">listing</span><span class="p">::</span> foo.py python
  2291. </pre><p>Will include the source code from <code class="docutils literal">foo.py</code>, highlight its syntax in python mode,
  2292. and also create a <code class="docutils literal">listings/foo.py.html</code> page (or in another directory, depending on
  2293. <code class="docutils literal">LISTINGS_FOLDER</code>) and the listing will have a title linking to it.</p>
  2294. <p>The stand-alone <code class="docutils literal">listings/</code> pages also support Jupyter notebooks, if they are
  2295. supported site-wide. You must have something for <code class="docutils literal">.ipynb</code> in POSTS or PAGES
  2296. for the feature to work.</p>
  2297. <p>Listings support the same options <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment">reST includes</a> support (including
  2298. various options for controlling which parts of the file are included), and also
  2299. a <code class="docutils literal">linenos</code> option for Sphinx compatibility.</p>
  2300. <p>The <code class="docutils literal">LISTINGS_FOLDER</code> configuration variable allows to specify a list of folders where
  2301. to fetch listings from together with subfolder of the <code class="docutils literal">output</code> folder where the
  2302. processed listings should be put in. The default is, <code class="docutils literal">LISTINGS_FOLDERS = {'listings': 'listings'}</code>,
  2303. which means that all source code files in <code class="docutils literal">listings</code> will be taken and stored in <code class="docutils literal">output/listings</code>.
  2304. Extending <code class="docutils literal">LISTINGS_FOLDERS</code> to <code class="docutils literal">{'listings': 'listings', 'code': <span class="pre">'formatted-code'}</span></code>
  2305. will additionally process all source code files in <code class="docutils literal">code</code> and put the results into
  2306. <code class="docutils literal"><span class="pre">output/formatted-code</span></code>.</p>
  2307. <aside class="admonition note">
  2308. <p class="admonition-title">Note</p>
  2309. <p>Formerly, <code class="docutils literal"><span class="pre">start-at</span></code> and <code class="docutils literal"><span class="pre">end-at</span></code> options were supported; however,
  2310. they do not work anymore (since v6.1.0) and you should now use <code class="docutils literal"><span class="pre">start-after</span></code>
  2311. and <code class="docutils literal"><span class="pre">end-before</span></code>, respectively. You can also use <code class="docutils literal"><span class="pre">start-line</span></code> and
  2312. <code class="docutils literal"><span class="pre">end-line</span></code>.</p>
  2313. </aside>
  2314. </section>
  2315. <section id="gist">
  2316. <h2><a class="toc-backref" href="#toc-entry-84" role="doc-backlink">Gist</a></h2>
  2317. <p>You can easily embed GitHub gists with this directive, like this:</p>
  2318. <pre class="code restructuredtext"><a name="rest_code_a6fd756ec51f4c629cdb6e9f81edeecf-1"></a><span class="p">..</span> <span class="ow">gist</span><span class="p">::</span> 2395294
  2319. </pre><p>Producing this:</p>
  2320. <script src="https://gist.github.com/2395294.js"></script><noscript><pre class="literal-block">#include &lt;stdlib.h&gt;
  2321. #include &lt;stdio.h&gt;
  2322. int nonHeapInt;
  2323. struct HeapObject
  2324. {
  2325. int x; // 因為如果找 x 的 pointer,實際上和找 HeapObject 的開頭 pointer 相同,
  2326. // 所以我們必需加一個y,讓我們指定 pointer 時不會指到 HeapObject 的開頭。
  2327. int y;
  2328. };
  2329. int main()
  2330. {
  2331. struct HeapObject * heapObject = malloc(sizeof(struct HeapObject));
  2332. nonHeapInt = 10;
  2333. heapObject-&gt;y = 20;
  2334. printf(&quot;Start nonHeapInt:%d\n&quot;, nonHeapInt);
  2335. printf(&quot;Start heapObject-&gt;y:%d\n&quot;, heapObject-&gt;y);
  2336. // free(&amp;nonHeapInt); // GCC 會警告,執行 glibc 會丟 invalid pointer exception
  2337. // free(&amp;(heapObject-&gt;y)); // 雖然不會景告,但 glibc 還是會丟 invalid pointer exception
  2338. printf(&quot;End nonHeapInt:%d\n&quot;, nonHeapInt);
  2339. printf(&quot;End heapObject-&gt;y:%d\n&quot;, heapObject-&gt;y);
  2340. }
  2341. </pre>
  2342. </noscript><p>This degrades gracefully if the browser doesn't support JavaScript.</p>
  2343. </section>
  2344. <section id="thumbnails">
  2345. <h2><a class="toc-backref" href="#toc-entry-85" role="doc-backlink">Thumbnails</a></h2>
  2346. <p>To include an image placed in the <code class="docutils literal">images</code> folder (or other folders defined in <code class="docutils literal">IMAGE_FOLDERS</code>), use the
  2347. <code class="docutils literal">thumbnail</code> directive, like this:</p>
  2348. <pre class="code restructuredtext"><a name="rest_code_549bffe9692c4ad7a4f4389128d42fa3-1"></a><span class="p">..</span> <span class="ow">thumbnail</span><span class="p">::</span> /images/tesla.jpg
  2349. <a name="rest_code_549bffe9692c4ad7a4f4389128d42fa3-2"></a> <span class="nc">:alt:</span> Nikola Tesla
  2350. </pre><p>The small thumbnail will be placed in the page, and it will be linked to the bigger
  2351. version of the image when clicked, using
  2352. <a class="reference external" href="https://feimosi.github.io/baguetteBox.js/">baguetteBox</a> by default. All options supported by
  2353. the reST <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#image">image</a>
  2354. directive are supported (except <code class="docutils literal">target</code>). Providing <code class="docutils literal">alt</code> is recommended,
  2355. as this is the image caption. If a body element is provided, the thumbnail will
  2356. mimic the behavior of the <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure">figure</a>
  2357. directive instead:</p>
  2358. <pre class="code restructuredtext"><a name="rest_code_37a0e080ea93497691ca445acb69483e-1"></a><span class="p">..</span> <span class="ow">thumbnail</span><span class="p">::</span> /images/tesla.jpg
  2359. <a name="rest_code_37a0e080ea93497691ca445acb69483e-2"></a> <span class="nc">:alt:</span> Nikola Tesla
  2360. <a name="rest_code_37a0e080ea93497691ca445acb69483e-3"></a>
  2361. <a name="rest_code_37a0e080ea93497691ca445acb69483e-4"></a> Nikola Tesla, the man that invented the 20th century.
  2362. </pre><p>If you want to include a thumbnail in a non-reST post, you need to produce at
  2363. least this basic HTML:</p>
  2364. <pre class="code html"><a name="rest_code_4fdc06777c7b4e77808ecc29f6a6f728-1"></a><span class="p">&lt;</span><span class="nt">a</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;reference&quot;</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;images/tesla.jpg&quot;</span> <span class="na">alt</span><span class="o">=</span><span class="s">&quot;Nikola Tesla&quot;</span><span class="p">&gt;&lt;</span><span class="nt">img</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;images/tesla.thumbnail.jpg&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">a</span><span class="p">&gt;</span>
  2365. </pre></section>
  2366. <section id="chart">
  2367. <h2><a class="toc-backref" href="#toc-entry-86" role="doc-backlink">Chart</a></h2>
  2368. <p>This directive is a thin wrapper around <a class="reference external" href="http://pygal.org/">Pygal</a> and will produce charts
  2369. as SVG files embedded directly in your pages.</p>
  2370. <p>Here's an example of how it works:</p>
  2371. <pre class="code restructuredtext"><a name="rest_code_e5fca258a8004eb1b5c935b4651c858d-1"></a><span class="p">..</span> <span class="ow">chart</span><span class="p">::</span> Bar
  2372. <a name="rest_code_e5fca258a8004eb1b5c935b4651c858d-2"></a> <span class="nc">:title:</span> &#39;Browser usage evolution (in %)&#39;
  2373. <a name="rest_code_e5fca258a8004eb1b5c935b4651c858d-3"></a> <span class="nc">:x_labels:</span> [&quot;2002&quot;, &quot;2003&quot;, &quot;2004&quot;, &quot;2005&quot;, &quot;2006&quot;, &quot;2007&quot;]
  2374. <a name="rest_code_e5fca258a8004eb1b5c935b4651c858d-4"></a>
  2375. <a name="rest_code_e5fca258a8004eb1b5c935b4651c858d-5"></a> &#39;Firefox&#39;, [None, None, 0, 16.6, 25, 31]
  2376. <a name="rest_code_e5fca258a8004eb1b5c935b4651c858d-6"></a> &#39;Chrome&#39;, [None, None, None, None, None, None]
  2377. <a name="rest_code_e5fca258a8004eb1b5c935b4651c858d-7"></a> &#39;IE&#39;, [85.8, 84.6, 84.7, 74.5, 66, 58.6]
  2378. <a name="rest_code_e5fca258a8004eb1b5c935b4651c858d-8"></a> &#39;Others&#39;, [14.2, 15.4, 15.3, 8.9, 9, 10.4]
  2379. </pre><p>The argument passed next to the directive (Bar in that example) is the type of chart, and can be one of
  2380. Line, StackedLine, Bar, StackedBar, HorizontalBar, XY, DateY, Pie, Radar, Dot, Funnel, Gauge, Pyramid. For
  2381. examples of what each kind of graph is, <a class="reference external" href="http://pygal.org/en/stable/documentation/types/index.html">check here</a></p>
  2382. <p>It can take <em>a lot</em> of options to let you customize the charts (in the example, title and x_labels).
  2383. You can use any option described in <a class="reference external" href="http://pygal.org/en/stable/documentation/configuration/chart.html">the pygal docs</a></p>
  2384. <p>Finally, the content of the directive is the actual data, in the form of a label and
  2385. a list of values, one series per line.</p>
  2386. <p>You can also specify a <code class="docutils literal">:data_file:</code> option as described in the documentation for the chart shortcut.</p>
  2387. </section>
  2388. <section id="doc">
  2389. <h2><a class="toc-backref" href="#toc-entry-87" role="doc-backlink">Doc</a></h2>
  2390. <p>This role is useful to make links to other post or page inside the same site.</p>
  2391. <p>Here's an example:</p>
  2392. <pre class="code restructuredtext"><a name="rest_code_43165e4b4c464fdeb21e96d1cd824902-1"></a>Take a look at <span class="na">:doc:</span><span class="nv">`my other post &lt;creating-a-theme&gt;`</span> about theme creating.
  2393. </pre><p>In this case we are giving the portion of text we want to link. So, the result will be:</p>
  2394. <blockquote>
  2395. <p>Take a look at <a class="reference external" href="/pages/creating-a-theme.html">my other post</a> about theme creating.</p>
  2396. </blockquote>
  2397. <p>If we want to use the post's title as the link's text, just do:</p>
  2398. <pre class="code restructuredtext"><a name="rest_code_57e5bf345f144cc699afaa614b8469f6-1"></a>Take a look at <span class="na">:doc:</span><span class="nv">`creating-a-theme`</span> to know how to do it.
  2399. </pre><p>and it will produce:</p>
  2400. <blockquote>
  2401. <p>Take a look at <a class="reference external" href="/pages/creating-a-theme.html">Creating a Theme</a> to know how to do it.</p>
  2402. </blockquote>
  2403. <p>The reference in angular brackets should be the <cite>slug</cite> for the target page. It supports a fragment, so
  2404. things like <code class="docutils literal"><span class="pre">&lt;creating-a-theme#starting-from-somewhere&gt;</span></code> should work. You can also use the title, and
  2405. Nikola will slugify it for you, so <code class="docutils literal">Creating a theme</code> is also supported.</p>
  2406. <p>Keep in mind that the important thing is the slug. No attempt is made to check if the fragment points to
  2407. an existing location in the page, and references that don't match any page's slugs will cause warnings.</p>
  2408. </section>
  2409. <section id="post-list">
  2410. <h2><a class="toc-backref" href="#toc-entry-88" role="doc-backlink">Post List</a></h2>
  2411. <aside class="admonition warning">
  2412. <p class="admonition-title">Warning</p>
  2413. <p>Any post or page that uses this directive will be considered out of date,
  2414. every time a post is added or deleted, causing maybe unnecessary rebuilds.</p>
  2415. <p>On the other hand, it will sometimes <strong>not</strong> be considered out of date if
  2416. a post content changes, so it can sometimes be shown outdated, in those
  2417. cases, use <code class="docutils literal">nikola build <span class="pre">-a</span></code> to force a total rebuild.</p>
  2418. </aside>
  2419. <p>This directive can be used to generate a list of posts. You could use it, for
  2420. example, to make a list of the latest 5 blog posts, or a list of all blog posts
  2421. with the tag <code class="docutils literal">nikola</code>:</p>
  2422. <pre class="code restructuredtext"><a name="rest_code_1fd4a24ebd0346c18850db884f8b1c5b-1"></a>Here are my 5 latest and greatest blog posts:
  2423. <a name="rest_code_1fd4a24ebd0346c18850db884f8b1c5b-2"></a>
  2424. <a name="rest_code_1fd4a24ebd0346c18850db884f8b1c5b-3"></a><span class="p">..</span> <span class="ow">post-list</span><span class="p">::</span>
  2425. <a name="rest_code_1fd4a24ebd0346c18850db884f8b1c5b-4"></a> <span class="nc">:stop:</span> 5
  2426. <a name="rest_code_1fd4a24ebd0346c18850db884f8b1c5b-5"></a>
  2427. <a name="rest_code_1fd4a24ebd0346c18850db884f8b1c5b-6"></a>These are all my posts about Nikola:
  2428. <a name="rest_code_1fd4a24ebd0346c18850db884f8b1c5b-7"></a>
  2429. <a name="rest_code_1fd4a24ebd0346c18850db884f8b1c5b-8"></a><span class="p">..</span> <span class="ow">post-list</span><span class="p">::</span>
  2430. <a name="rest_code_1fd4a24ebd0346c18850db884f8b1c5b-9"></a> <span class="nc">:tags:</span> nikola
  2431. </pre><p>Using shortcode syntax (for other compilers):</p>
  2432. <pre class="code text"><a name="rest_code_7897e663e40d4ffdb57699fb19e12cb0-1"></a>{{% post-list stop=5 %}}{{% /post-list %}}
  2433. </pre><p>The following options are recognized:</p>
  2434. <ul class="simple">
  2435. <li><dl class="simple">
  2436. <dt><code class="docutils literal">start</code><span class="classifier">integer</span></dt>
  2437. <dd><p>The index of the first post to show.
  2438. A negative value like <code class="docutils literal"><span class="pre">-3</span></code> will show the <em>last</em> three posts in the
  2439. post-list.
  2440. Defaults to None.</p>
  2441. </dd>
  2442. </dl>
  2443. </li>
  2444. <li><dl class="simple">
  2445. <dt><code class="docutils literal">stop</code><span class="classifier">integer</span></dt>
  2446. <dd><p>The index of the last post to show.
  2447. A value negative value like <code class="docutils literal"><span class="pre">-1</span></code> will show every post, but not the
  2448. <em>last</em> in the post-list.
  2449. Defaults to None.</p>
  2450. </dd>
  2451. </dl>
  2452. </li>
  2453. <li><dl class="simple">
  2454. <dt><code class="docutils literal">reverse</code><span class="classifier">flag</span></dt>
  2455. <dd><p>Reverse the order of the post-list.
  2456. Defaults is to not reverse the order of posts.</p>
  2457. </dd>
  2458. </dl>
  2459. </li>
  2460. <li><dl class="simple">
  2461. <dt><code class="docutils literal">sort</code>: string</dt>
  2462. <dd><p>Sort post list by one of each post's attributes, usually <code class="docutils literal">title</code> or a
  2463. custom <code class="docutils literal">priority</code>. Defaults to None (chronological sorting).</p>
  2464. </dd>
  2465. </dl>
  2466. </li>
  2467. <li><dl class="simple">
  2468. <dt><code class="docutils literal">date</code>: string</dt>
  2469. <dd><p>Show posts that match date range specified by this option. Format:</p>
  2470. <ul>
  2471. <li><p>comma-separated clauses (AND)</p></li>
  2472. <li><dl class="simple">
  2473. <dt>clause: attribute comparison_operator value (spaces optional)</dt>
  2474. <dd><ul>
  2475. <li><p>attribute: year, month, day, hour, month, second, weekday, isoweekday; or empty for full datetime</p></li>
  2476. <li><p>comparison_operator: == != &lt;= &gt;= &lt; &gt;</p></li>
  2477. <li><p>value: integer, 'now', 'today', or dateutil-compatible date input</p></li>
  2478. </ul>
  2479. </dd>
  2480. </dl>
  2481. </li>
  2482. </ul>
  2483. </dd>
  2484. </dl>
  2485. </li>
  2486. <li><dl class="simple">
  2487. <dt><code class="docutils literal">tags</code><span class="classifier">string [, string...]</span></dt>
  2488. <dd><p>Filter posts to show only posts having at least one of the <code class="docutils literal">tags</code>.
  2489. Defaults to None.</p>
  2490. </dd>
  2491. </dl>
  2492. </li>
  2493. <li><dl class="simple">
  2494. <dt><code class="docutils literal">require_all_tags</code><span class="classifier">flag</span></dt>
  2495. <dd><p>Change tag filter behaviour to show only posts that have all specified <code class="docutils literal">tags</code>.
  2496. Defaults to False.</p>
  2497. </dd>
  2498. </dl>
  2499. </li>
  2500. <li><dl class="simple">
  2501. <dt><code class="docutils literal">categories</code><span class="classifier">string [, string...]</span></dt>
  2502. <dd><p>Filter posts to show only posts having one of the <code class="docutils literal">categories</code>.
  2503. Defaults to None.</p>
  2504. </dd>
  2505. </dl>
  2506. </li>
  2507. <li><dl class="simple">
  2508. <dt><code class="docutils literal">slugs</code><span class="classifier">string [, string...]</span></dt>
  2509. <dd><p>Filter posts to show only posts having at least one of the <code class="docutils literal">slugs</code>.
  2510. Defaults to None.</p>
  2511. </dd>
  2512. </dl>
  2513. </li>
  2514. <li><dl class="simple">
  2515. <dt><code class="docutils literal">post_type</code> (or <code class="docutils literal">type</code>)<span class="classifier">string</span></dt>
  2516. <dd><p>Show only <code class="docutils literal">posts</code>, <code class="docutils literal">pages</code> or <code class="docutils literal">all</code>.
  2517. Replaces <code class="docutils literal">all</code>. Defaults to <code class="docutils literal">posts</code>.</p>
  2518. </dd>
  2519. </dl>
  2520. </li>
  2521. <li><dl class="simple">
  2522. <dt><code class="docutils literal">all</code><span class="classifier">flag</span></dt>
  2523. <dd><p>(deprecated, use <code class="docutils literal">post_type</code> instead)
  2524. Shows all posts and pages in the post list. Defaults to show only posts.</p>
  2525. </dd>
  2526. </dl>
  2527. </li>
  2528. <li><dl class="simple">
  2529. <dt><code class="docutils literal">lang</code><span class="classifier">string</span></dt>
  2530. <dd><p>The language of post <em>titles</em> and <em>links</em>.
  2531. Defaults to default language.</p>
  2532. </dd>
  2533. </dl>
  2534. </li>
  2535. <li><dl class="simple">
  2536. <dt><code class="docutils literal">template</code><span class="classifier">string</span></dt>
  2537. <dd><p>The name of an alternative template to render the post-list.
  2538. Defaults to <code class="docutils literal">post_list_directive.tmpl</code></p>
  2539. </dd>
  2540. </dl>
  2541. </li>
  2542. <li><dl class="simple">
  2543. <dt><code class="docutils literal">id</code><span class="classifier">string</span></dt>
  2544. <dd><p>A manual id for the post list.
  2545. Defaults to a random name composed by <code class="docutils literal">'post_list_' + <span class="pre">uuid.uuid4().hex</span></code>.</p>
  2546. </dd>
  2547. </dl>
  2548. </li>
  2549. </ul>
  2550. <p>The post list directive uses the <code class="docutils literal">post_list_directive.tmpl</code> template file (or
  2551. another one, if you use the <code class="docutils literal">template</code> option) to generate the list's HTML. By
  2552. default, this is an unordered list with dates and clickable post titles. See
  2553. the template file in Nikola's base theme for an example of how this works.</p>
  2554. <p>The list may fail to update in some cases, please run <code class="docutils literal">nikola build <span class="pre">-a</span></code> with
  2555. the appropriate path if this happens.</p>
  2556. <p>We recommend using pages with dates in the past (1970-01-01) to avoid
  2557. dependency issues.</p>
  2558. <p>If you are using this as a shortcode, flags (<code class="docutils literal">reverse</code>, <code class="docutils literal">all</code>) are meant to be used
  2559. with a <code class="docutils literal">True</code> argument, eg. <code class="docutils literal">all=True</code>.</p>
  2560. <aside class="sidebar">
  2561. <p class="sidebar-title">Docutils Configuration</p>
  2562. <p>ReStructured Text is &quot;compiled&quot; by docutils, which supports a number of
  2563. configuration options. It would be difficult to integrate them all into
  2564. Nikola's configuration, so you can just put a <code class="docutils literal">docutils.conf</code> next
  2565. to your <code class="docutils literal">conf.py</code> and any settings in its <code class="docutils literal">[nikola]</code> section will be used.</p>
  2566. <p>More information in the <a class="reference external" href="https://docutils.sourceforge.io/docs/user/config.html">docutils configuration reference</a></p>
  2567. </aside>
  2568. </section>
  2569. </section>
  2570. <section id="importing-your-wordpress-site-into-nikola">
  2571. <h1><a class="toc-backref" href="#toc-entry-89" role="doc-backlink">Importing your WordPress site into Nikola</a></h1>
  2572. <p>If you like Nikola, and want to start using it, but you have a WordPress blog, Nikola
  2573. supports importing it. Here are the steps to do it:</p>
  2574. <ol class="arabic simple">
  2575. <li><p>Get an XML dump of your site <a class="footnote-reference brackets" href="#footnote-1" id="footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></li>
  2576. <li><p><code class="docutils literal">nikola import_wordpress <span class="pre">mysite.wordpress.2012-12-20.xml</span></code></p></li>
  2577. </ol>
  2578. <p>After some time, this will create a <code class="docutils literal">new_site</code> folder with all your data. It currently supports
  2579. the following:</p>
  2580. <ul>
  2581. <li><p>All your posts and pages</p></li>
  2582. <li><p>Keeps “draft” status</p></li>
  2583. <li><p>Your tags and categories</p></li>
  2584. <li><p>Imports your attachments and fixes links to point to the right places</p></li>
  2585. <li><p>Will try to add redirects that send the old post URLs to the new ones</p></li>
  2586. <li><p>Will give you a URL map so you know where each old post was</p>
  2587. <p>This is also useful for DISQUS thread migration, or server-based 301
  2588. redirects!</p>
  2589. </li>
  2590. <li><p>Allows you to export your comments with each post</p></li>
  2591. <li><p>Exports information on attachments per post</p></li>
  2592. <li><p>There are different methods to transfer the content of your posts:</p>
  2593. <ul>
  2594. <li><p>You can convert them to HTML with the WordPress page compiler plugin
  2595. for Nikola. This will format the posts including supported shortcodes
  2596. the same way as WordPress does. Use the <code class="docutils literal"><span class="pre">--transform-to-html</span></code> option
  2597. to convert your posts to HTML.</p>
  2598. <p>If you use this option, you do not need to install the plugin
  2599. permanently. You can ask Nikola to install the plugin into the subdirectory
  2600. <code class="docutils literal">plugins</code> of the current working directory by specifying
  2601. the <code class="docutils literal"><span class="pre">--install-wordpress-compiler</span></code> option.</p>
  2602. </li>
  2603. <li><p>You can leave the posts the way they are and use the WordPress page
  2604. compiler plugin to render them when building your new blog. This also
  2605. allows you to create new posts using the WordPress syntax, or to manually
  2606. add more shortcode plugins later. Use the <code class="docutils literal"><span class="pre">--use-wordpress-compiler</span></code>
  2607. option to not touch your posts.</p>
  2608. <p>If you want to use this option, you have to install the plugin permanently.
  2609. You can ask Nikola to install the plugin into your new site by specifying
  2610. the <code class="docutils literal"><span class="pre">--install-wordpress-compiler</span></code> option.</p>
  2611. </li>
  2612. <li><p>You can let Nikola convert your posts to Markdown. This is <em>not</em> error
  2613. free, because WordPress uses some unholy mix of HTML and strange things.
  2614. This is the default option and requires no plugins.</p></li>
  2615. </ul>
  2616. <p>You will find your old posts in <code class="docutils literal"><span class="pre">new_site/posts/post-title.html</span></code> in the first case,
  2617. <code class="docutils literal"><span class="pre">new_site/posts/post-title.wp</span></code> in the second case or <code class="docutils literal"><span class="pre">new_site/posts/post-title.md</span></code>
  2618. in the last case if you need to edit or fix any of them.</p>
  2619. <p>Please note that the page compiler currently only supports the <code class="docutils literal">[code]</code> shortcode,
  2620. but other shortcodes can be supported via plugins.</p>
  2621. <p>Also note that the WordPress page compiler is licensed under GPL v2 since
  2622. it uses code from WordPress itself, while Nikola is licensed under the more
  2623. liberal MIT license.</p>
  2624. </li>
  2625. </ul>
  2626. <p>This feature is a work in progress, and the only way to improve it is to have it used for
  2627. as many sites as possible and make it work better each time, so we are happy to get requests
  2628. about it.</p>
  2629. <aside class="footnote-list brackets">
  2630. <aside class="footnote brackets" id="footnote-1" role="note">
  2631. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-1">1</a><span class="fn-bracket">]</span></span>
  2632. <p>The dump needs to be in 1.2 format. You can check by reading it, it should say
  2633. <code class="docutils literal"><span class="pre">xmlns:excerpt=&quot;http://wordpress.org/export/1.2/excerpt/&quot;</span></code> near the top of the
  2634. file. If it says <code class="docutils literal">1.1</code> instead of <code class="docutils literal">1.2</code> you will have to update your
  2635. WordPress before dumping.</p>
  2636. <p>Other versions may or may not work.</p>
  2637. </aside>
  2638. </aside>
  2639. <section id="importing-to-a-custom-location-or-into-an-existing-site">
  2640. <h2><a class="toc-backref" href="#toc-entry-90" role="doc-backlink">Importing to a custom location or into an existing site</a></h2>
  2641. <p>It is possible to either import into a location you desire or into an already existing Nikola site.
  2642. To do so you can specify a location after the dump:</p>
  2643. <pre class="code console"><a name="rest_code_909cd90914e441c2baf7584322209a79-1"></a><span class="gp">$</span> nikola import_wordpress mysite.wordpress.2012-12-20.xml -o import_location
  2644. </pre><p>With this command Nikola will import into the folder <code class="docutils literal">import_location</code>.</p>
  2645. <p>If the folder already exists Nikola will not overwrite an existing <code class="docutils literal">conf.py</code>.
  2646. Instead a new file with a timestamp at the end of the filename will be created.</p>
  2647. </section>
  2648. </section>
  2649. <section id="using-twitter-cards">
  2650. <h1><a class="toc-backref" href="#toc-entry-91" role="doc-backlink">Using Twitter Cards</a></h1>
  2651. <p>Nikola supports Twitter Card summaries, but they are disabled by default.</p>
  2652. <p>Twitter Cards enable you to show additional information in Tweets that link
  2653. to your content.
  2654. Nikola supports <a class="reference external" href="https://dev.twitter.com/docs/cards">Twitter Cards</a>.
  2655. They are implemented to use <em>Open Graph</em> tags whenever possible.</p>
  2656. <p>Images displayed come from the <cite>previewimage</cite> meta tag.</p>
  2657. <p>You can specify the card type by using the <cite>card</cite> parameter in TWITTER_CARD.</p>
  2658. <p>To enable and configure your use of Twitter Cards, please modify the
  2659. corresponding lines in your <code class="docutils literal">conf.py</code>:</p>
  2660. <pre class="code python"><a name="rest_code_d103c0710e8c4cf098b7a7ddaa447a36-1"></a><span class="n">TWITTER_CARD</span> <span class="o">=</span> <span class="p">{</span>
  2661. <a name="rest_code_d103c0710e8c4cf098b7a7ddaa447a36-2"></a> <span class="s1">&#39;use_twitter_cards&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span> <span class="c1"># enable Twitter Cards</span>
  2662. <a name="rest_code_d103c0710e8c4cf098b7a7ddaa447a36-3"></a> <span class="s1">&#39;card&#39;</span><span class="p">:</span> <span class="s1">&#39;summary&#39;</span><span class="p">,</span> <span class="c1"># Card type, you can also use &#39;summary_large_image&#39;,</span>
  2663. <a name="rest_code_d103c0710e8c4cf098b7a7ddaa447a36-4"></a> <span class="c1"># see https://dev.twitter.com/cards/types</span>
  2664. <a name="rest_code_d103c0710e8c4cf098b7a7ddaa447a36-5"></a> <span class="s1">&#39;site&#39;</span><span class="p">:</span> <span class="s1">&#39;@website&#39;</span><span class="p">,</span> <span class="c1"># twitter nick for the website</span>
  2665. <a name="rest_code_d103c0710e8c4cf098b7a7ddaa447a36-6"></a> <span class="s1">&#39;creator&#39;</span><span class="p">:</span> <span class="s1">&#39;@username&#39;</span><span class="p">,</span> <span class="c1"># Username for the content creator / author.</span>
  2666. <a name="rest_code_d103c0710e8c4cf098b7a7ddaa447a36-7"></a><span class="p">}</span>
  2667. </pre></section>
  2668. <section id="custom-plugins">
  2669. <h1><a class="toc-backref" href="#toc-entry-92" role="doc-backlink">Custom Plugins</a></h1>
  2670. <p>You can create your own plugins (see <a class="reference external" href="/pages/extending.html">Extending Nikola</a>) and use them in your own
  2671. site by putting them in a <code class="docutils literal">plugins/</code> folder. You can also put them in
  2672. directories listed in the <code class="docutils literal">EXTRA_PLUGINS_DIRS</code> configuration variable.</p>
  2673. </section>
  2674. <section id="getting-extra-plugins">
  2675. <h1><a class="toc-backref" href="#toc-entry-93" role="doc-backlink">Getting Extra Plugins</a></h1>
  2676. <p>If you want extra plugins, there is also the <a class="reference external" href="https://plugins.getnikola.com/">Plugins Index</a>.</p>
  2677. <p>Similarly to themes, there is a nice, built-in command to manage them —
  2678. <code class="docutils literal">plugin</code>:</p>
  2679. <pre class="code console"><a name="rest_code_3afc51eaae9249348be77faf328a4711-1"></a><span class="gp">$</span> nikola plugin -l
  2680. <a name="rest_code_3afc51eaae9249348be77faf328a4711-2"></a><span class="go">Plugins:</span>
  2681. <a name="rest_code_3afc51eaae9249348be77faf328a4711-3"></a><span class="go">--------</span>
  2682. <a name="rest_code_3afc51eaae9249348be77faf328a4711-4"></a><span class="go">helloworld</span>
  2683. <a name="rest_code_3afc51eaae9249348be77faf328a4711-5"></a><span class="go">tags</span>
  2684. <a name="rest_code_3afc51eaae9249348be77faf328a4711-6"></a><span class="go">⋮</span>
  2685. <a name="rest_code_3afc51eaae9249348be77faf328a4711-7"></a><span class="go">⋮</span>
  2686. <a name="rest_code_3afc51eaae9249348be77faf328a4711-8"></a>
  2687. <a name="rest_code_3afc51eaae9249348be77faf328a4711-9"></a><span class="gp">$</span> nikola plugin --install helloworld
  2688. <a name="rest_code_3afc51eaae9249348be77faf328a4711-10"></a><span class="go">[2013-10-12T16:51:56Z] NOTICE: install_plugin: Downloading: https://plugins.getnikola.com/v6/helloworld.zip</span>
  2689. <a name="rest_code_3afc51eaae9249348be77faf328a4711-11"></a><span class="go">[2013-10-12T16:51:58Z] NOTICE: install_plugin: Extracting: helloworld into plugins</span>
  2690. <a name="rest_code_3afc51eaae9249348be77faf328a4711-12"></a><span class="go">plugins/helloworld/requirements.txt</span>
  2691. <a name="rest_code_3afc51eaae9249348be77faf328a4711-13"></a><span class="go">[2013-10-12T16:51:58Z] NOTICE: install_plugin: This plugin has Python dependencies.</span>
  2692. <a name="rest_code_3afc51eaae9249348be77faf328a4711-14"></a><span class="go">[2013-10-12T16:51:58Z] NOTICE: install_plugin: Installing dependencies with pip...</span>
  2693. <a name="rest_code_3afc51eaae9249348be77faf328a4711-15"></a><span class="go">⋮</span>
  2694. <a name="rest_code_3afc51eaae9249348be77faf328a4711-16"></a><span class="go">⋮</span>
  2695. <a name="rest_code_3afc51eaae9249348be77faf328a4711-17"></a><span class="go">[2013-10-12T16:51:59Z] NOTICE: install_plugin: Dependency installation succeeded.</span>
  2696. <a name="rest_code_3afc51eaae9249348be77faf328a4711-18"></a><span class="go">[2013-10-12T16:51:59Z] NOTICE: install_plugin: This plugin has a sample config file.</span>
  2697. <a name="rest_code_3afc51eaae9249348be77faf328a4711-19"></a><span class="go">Contents of the conf.py.sample file:</span>
  2698. <a name="rest_code_3afc51eaae9249348be77faf328a4711-20"></a>
  2699. <a name="rest_code_3afc51eaae9249348be77faf328a4711-21"></a><span class="gp"> #</span> Should the Hello World plugin say “BYE” instead?
  2700. <a name="rest_code_3afc51eaae9249348be77faf328a4711-22"></a><span class="go"> BYE_WORLD = False</span>
  2701. </pre><p>Then you also can uninstall your plugins:</p>
  2702. <pre class="code console"><a name="rest_code_a34dbbe949e04b83b778e7d599622eae-1"></a><span class="gp">$</span> nikola plugin --uninstall tags
  2703. <a name="rest_code_a34dbbe949e04b83b778e7d599622eae-2"></a><span class="go">[2014-04-15T08:59:24Z] WARNING: plugin: About to uninstall plugin: tags</span>
  2704. <a name="rest_code_a34dbbe949e04b83b778e7d599622eae-3"></a><span class="go">[2014-04-15T08:59:24Z] WARNING: plugin: This will delete /home/ralsina/foo/plugins/tags</span>
  2705. <a name="rest_code_a34dbbe949e04b83b778e7d599622eae-4"></a><span class="go">Are you sure? [y/n] y</span>
  2706. <a name="rest_code_a34dbbe949e04b83b778e7d599622eae-5"></a><span class="go">[2014-04-15T08:59:26Z] WARNING: plugin: Removing /home/ralsina/foo/plugins/tags</span>
  2707. </pre><p>And upgrade them:</p>
  2708. <pre class="code console"><a name="rest_code_24342a29a808464f92514eb66426302c-1"></a><span class="gp">$</span> nikola plugin --upgrade
  2709. <a name="rest_code_24342a29a808464f92514eb66426302c-2"></a><span class="go">[2014-04-15T09:00:18Z] WARNING: plugin: This is not very smart, it just reinstalls some plugins and hopes for the best</span>
  2710. <a name="rest_code_24342a29a808464f92514eb66426302c-3"></a><span class="go">Will upgrade 1 plugins: graphviz</span>
  2711. <a name="rest_code_24342a29a808464f92514eb66426302c-4"></a><span class="go">Upgrading graphviz</span>
  2712. <a name="rest_code_24342a29a808464f92514eb66426302c-5"></a><span class="go">[2014-04-15T09:00:20Z] INFO: plugin: Downloading: https://plugins.getnikola.com/v7/graphviz.zip</span>
  2713. <a name="rest_code_24342a29a808464f92514eb66426302c-6"></a><span class="go">[2014-04-15T09:00:20Z] INFO: plugin: Extracting: graphviz into /home/ralsina/.nikola/plugins/</span>
  2714. <a name="rest_code_24342a29a808464f92514eb66426302c-7"></a><span class="go">[2014-04-15T09:00:20Z] NOTICE: plugin: This plugin has third-party dependencies you need to install manually.</span>
  2715. <a name="rest_code_24342a29a808464f92514eb66426302c-8"></a><span class="go">Contents of the requirements-nonpy.txt file:</span>
  2716. <a name="rest_code_24342a29a808464f92514eb66426302c-9"></a>
  2717. <a name="rest_code_24342a29a808464f92514eb66426302c-10"></a><span class="go"> Graphviz</span>
  2718. <a name="rest_code_24342a29a808464f92514eb66426302c-11"></a><span class="go"> https://www.graphviz.org/</span>
  2719. <a name="rest_code_24342a29a808464f92514eb66426302c-12"></a>
  2720. <a name="rest_code_24342a29a808464f92514eb66426302c-13"></a><span class="go">You have to install those yourself or through a package manager.</span>
  2721. </pre><p>You can also share plugins you created with the community! Visit the
  2722. <a class="reference external" href="https://github.com/getnikola/plugins">GitHub repository</a> to find out more.</p>
  2723. <p>You can use the plugins in this repository without installing them into your
  2724. site, by cloning the repository and adding the path of the plugins directory to
  2725. the <code class="docutils literal">EXTRA_PLUGINS_DIRS</code> list in your configuration.</p>
  2726. </section>
  2727. <section id="advanced-features">
  2728. <h1><a class="toc-backref" href="#toc-entry-94" role="doc-backlink">Advanced Features</a></h1>
  2729. <section id="debugging">
  2730. <h2><a class="toc-backref" href="#toc-entry-95" role="doc-backlink">Debugging</a></h2>
  2731. <p>For pdb debugging in Nikola, you should use <code class="docutils literal">doit.tools.set_trace()</code> instead
  2732. of the usual pdb call. By default, doit (and thus Nikola) redirects stdout and
  2733. stderr. Thus, you must use the different call. (Alternatively, you could run
  2734. with <code class="docutils literal">nikola build <span class="pre">-v</span> 2</code>, which disables the redirections.)</p>
  2735. <p>To show more logging messages, as well as full tracebacks, you need to set an
  2736. environment variable: <code class="docutils literal">NIKOLA_DEBUG=1</code>. If you want to only see tracebacks,
  2737. set <code class="docutils literal">NIKOLA_SHOW_TRACEBACKS=1</code>.</p>
  2738. </section>
  2739. <section id="shell-tab-completion">
  2740. <h2><a class="toc-backref" href="#toc-entry-96" role="doc-backlink">Shell Tab Completion</a></h2>
  2741. <p>Since Nikola is a command line tool, and this is the 21st century, it's handy to have smart tab-completion
  2742. so that you don't have to type the full commands.</p>
  2743. <p>To enable this, you can use the <code class="docutils literal">nikola tabcompletion</code> command like this,
  2744. depending on your shell:</p>
  2745. <pre class="code console"><a name="rest_code_11b92258c62841bb95f453aef9a976b4-1"></a><span class="gp">$</span> nikola tabcompletion --shell bash --hardcode-tasks &gt; _nikola_bash
  2746. <a name="rest_code_11b92258c62841bb95f453aef9a976b4-2"></a><span class="gp">$</span> nikola tabcompletion --shell zsh --hardcode-tasks &gt; _nikola_zsh
  2747. </pre><p>The <code class="docutils literal"><span class="pre">--hardcode-tasks</span></code> adds tasks to the completion and may need updating periodically.</p>
  2748. <p>Please refer to your shell’s documentation for help on how to use those files.</p>
  2749. </section>
  2750. </section>
  2751. <section id="license">
  2752. <h1><a class="toc-backref" href="#toc-entry-97" role="doc-backlink">License</a></h1>
  2753. <p>Nikola is released under the <a class="reference external" href="https://getnikola.com/license.html">MIT license</a>, which is a free software license. Some
  2754. components shipped along with Nikola, or required by it are released under
  2755. other licenses.</p>
  2756. <p>If you are not familiar with free software licensing, here is a brief
  2757. explanation (this is NOT legal advice): In general, you can do pretty much
  2758. anything you want — including modifying Nikola, using and redistributing the
  2759. original version or the your modified version. However, if you redistribute
  2760. Nikola to someone else, either a modified version or the original version, the
  2761. full copyright notice and license text must be included in your distribution.
  2762. Nikola is provided “as is”, and the Nikola contributors are not liable for any
  2763. damage caused by the software. Read the <a class="reference external" href="https://getnikola.com/license.html">full license text</a> for details.</p>
  2764. </section>