Nikola Documentation

Those are the docs for the current GitHub master. It might be incompatible with the stable release. The docs for the stable release are available on the Nikola website.

Please note that some examples of Nikola-specific reST syntax might not be visible in this version of Nikola docs.

Nikola Documentation

• 1. The Nikola Handbook
  • 1.1. All You Need to Know
  • 1.2. What’s Nikola and what can you do with it?
  • 1.3. Getting Help
  • 1.4. Why Static?
  • 1.5. Components
  • 1.6. Getting Started
  • 1.7. Creating a Blog Post
    • 1.7.1. Metadata fields
      • 1.7.1.1. Basic
      • 1.7.1.2. Extra
    • 1.7.2. Metadata formats
      • 1.7.2.1. reST-style comments
      • 1.7.2.2. Two-file format
      • 1.7.2.3. Jupyter Notebook metadata
      • 1.7.2.4. YAML metadata
      • 1.7.2.5. TOML metadata
      • 1.7.2.6. reST docinfo
      • 1.7.2.7. Pelican/Markdown metadata
      • 1.7.2.8. HTML meta tags
      • 1.7.2.9. Mapping metadata from other formats
    • 1.7.3. Multilingual posts
    • 1.7.4. How does Nikola decide where posts should go?
    • 1.7.5. The new_post command
    • 1.7.6. Teasers
    • 1.7.7. Drafts
    • 1.7.8. Private Posts
    • 1.7.9. Featured Posts
    • 1.7.10. Queuing Posts
    • 1.7.11. Post Types
    • 1.7.12. Indexes
      • 1.7.12.1. Settings
      • 1.7.12.2. Static indexes
    • 1.7.13. Post taxonomy
      • 1.7.13.1. Tags
      • 1.7.13.2. Categories
      • 1.7.13.3. Configuring tags and categories
    • 1.7.14. What if I don’t want a blog?
  • 1.8. Creating a Page
  • 1.9. Supported input formats
    • 1.9.1. Configuring other input formats
      • 1.9.1.1. Markdown
      • 1.9.1.2. Jupyter Notebook
      • 1.9.1.3. HTML
      • 1.9.1.4. PHP
      • 1.9.1.5. Pandoc
  • 1.10. Shortcodes
    • 1.10.1. Using a shortcode
    • 1.10.2. Built-in shortcodes
    • 1.10.3. Community shortcodes
    • 1.10.4. Template-based shortcodes
  • 1.11. The Global Context and Data files
  • 1.12. Redirections
  • 1.13. Configuration
  • 1.14. Customizing Your Site
  • 1.15. Fancy Dates
  • 1.16. Adding Files
  • 1.17. Custom Themes
  • 1.18. Getting Extra Themes
  • 1.19. Deployment
    • 1.19.1. Deploying to GitHub
    • 1.19.2. Automated rebuilds (GitHub Actions, GitLab)
  • 1.20. Comments
  • 1.21. Images and Galleries
    • 1.21.1. Embedding Images
  • 1.22. Handling EXIF Data
    • 1.22.1. Strip all EXIF data
    • 1.22.2. Preserve all EXIF data
    • 1.22.3. Preserve some EXIF data
  • 1.23. Handling ICC Profiles
  • 1.24. Post Processing Filters
  • 1.25. Optimizing Your Website
  • 1.26. Math
    • 1.26.1. Configuration
    • 1.26.2. Inline usage
    • 1.26.3. Display usage
  • 1.27. reStructuredText Extensions
    • 1.27.1. Includes
    • 1.27.2. Media
    • 1.27.3. YouTube
    • 1.27.4. Vimeo
    • 1.27.5. Soundcloud
    • 1.27.6. Code
    • 1.27.7. Listing
    • 1.27.8. Gist
    • 1.27.9. Thumbnails
    • 1.27.10. Chart
    • 1.27.11. Doc
    • 1.27.12. Post List
  • 1.28. Importing your WordPress site into Nikola
    • 1.28.1. Importing to a custom location or into an existing site
  • 1.29. Using Twitter Cards
  • 1.30. Custom Plugins
  • 1.31. Getting Extra Plugins
  • 1.32. Advanced Features
    • 1.32.1. Debugging
    • 1.32.2. Shell Tab Completion
  • 1.33. License
• 2. Creating a Site (Not a Blog) with Nikola
• 3. Creating a Theme
  • 3.1. Checking It Out
  • 3.2. Starting From Somewhere
  • 3.3. Basic CSS
  • 3.4. Page Layout
  • 3.5. Typography
  • 3.6. Customization
  • 3.7. Bundles
  • 3.8. The End
• 4. Theming Nikola
  • 4.1. The Structure
  • 4.2. Theme meta files
  • 4.3. Templates
  • 4.4. Built-in templates
  • 4.5. Variables available in templates
  • 4.6. Customizing themes to user color preference, colorizing category names
  • 4.7. Identifying and customizing different kinds of pages with a shared template
  • 4.8. Messages and Translations
  • 4.9. Configuration of the raw template engine
  • 4.10. LESS and Sass
• 5. Template variables
  • 5.1. Global variables
  • 5.2. Per-page local variables
  • 5.3. Variables available in post pages (post.tmpl, page.tmpl etc.)
  • 5.4. Variables available in post lists
  • 5.5. Variables available in indexes
  • 5.6. Variables available in taxonomies
    • 5.6.1. Templates and settings used by taxonomies
    • 5.6.2. Classification overviews
    • 5.6.3. Classification pages (lists)
    • 5.6.4. Subclassification page
    • 5.6.5. Hierarchical lists
  • 5.7. Variables available in archives
  • 5.8. Variables available in author pages
  • 5.9. Variables available in category pages
  • 5.10. Variables available in galleries
  • 5.11. Variables available in listings
  • 5.12. Variables available in tag pages
  • 5.13. Variables available in the “Tags and categories” page (tags.tmpl)
  • 5.14. Variables available in shortcodes
  • 5.15. Variables available in post lists
  • 5.16. Post object attributes
• 6. Extending Nikola
  • 6.1. Available Plugin Categories
    • 6.1.1. Command Plugins
    • 6.1.2. TemplateSystem Plugins
    • 6.1.3. Task Plugins
    • 6.1.4. PageCompiler Plugins
    • 6.1.5. MetadataExtractor Plugins
    • 6.1.6. RestExtension Plugins
    • 6.1.7. MarkdownExtension Plugins
    • 6.1.8. SignalHandler Plugins
    • 6.1.9. ConfigPlugin Plugins
    • 6.1.10. CommentSystem Plugins
    • 6.1.11. Shortcode Plugins
    • 6.1.12. PostScanner Plugins
  • 6.2. Plugin Index
  • 6.3. Path/Link Resolution Mechanism
  • 6.4. Template Hooks
  • 6.5. Shortcodes
    • 6.5.1. Template-based Shortcodes
  • 6.6. State and Cache
  • 6.7. Logging
  • 6.8. Template and Dependency Injection
• 7. Nikola Internals
  • 7.1. The Build Command
  • 7.2. Posts and Pages
    • 7.2.1. Nikola Architecture
• 8. Using Alternative Social Buttons with Nikola
  • 8.1. The Default
  • 8.2. ShareNice
  • 8.3. SocialSharePrivacy
    • 8.3.1. The Hard Way
    • 8.3.2. The Easy Way
• 9. Path Handlers for Nikola
• 10. Support and Contact
  • 10.1. Help and Support
    • 10.1.1. Plugins and Themes
  • 10.2. Report a Bug, Request a Feature
  • 10.3. Administrativia
    • 10.3.1. Administrators

Autogenerated Code Documentation

• 1. Code Documentation
  • 1.1. nikola package
    • 1.1.1. Subpackages
      • 1.1.1.1. nikola.packages package
        • 1.1.1.1.1. Subpackages
      • 1.1.1.2. nikola.plugins package
        • 1.1.1.2.1. Subpackages
        • 1.1.1.2.2. Submodules
        • 1.1.1.2.3. nikola.plugins.basic_import module
    • 1.1.2. Submodules
    • 1.1.3. nikola.filters module
      • add_header_permalinks()
      • apply_to_binary_file()
      • apply_to_text_file()
      • closure_compiler()
      • cssminify()
      • deduplicate_ids()
      • html5lib_minify()
      • html5lib_xmllike()
      • html_tidy_mini()
      • html_tidy_nowrap()
      • html_tidy_withconfig()
      • html_tidy_wrap()
      • html_tidy_wrap_attr()
      • jpegoptim()
      • jpegoptim_progressive()
      • jsminify()
      • jsonminify()
      • list_replace()
      • minify_lines()
      • normalize_html()
      • optipng()
      • php_template_injection()
      • runinplace()
      • typogrify()
      • typogrify_custom()
      • typogrify_oldschool()
      • typogrify_sans_widont()
      • xmlminify()
      • yui_compressor()
    • 1.1.4. nikola.hierarchy_utils module
      • TreeNode
        • TreeNode.get_children()
        • TreeNode.get_path()
        • TreeNode.indent_change_after
        • TreeNode.indent_change_before
        • TreeNode.indent_levels
      • clone_treenode()
      • flatten_tree_structure()
      • join_hierarchical_category_path()
      • parse_escaped_hierarchical_category_name()
      • sort_classifications()
    • 1.1.5. nikola.image_processing module
      • ImageProcessor
        • ImageProcessor.dates
        • ImageProcessor.filter_exif()
        • ImageProcessor.image_date()
        • ImageProcessor.image_ext_list_builtin
        • ImageProcessor.logger
        • ImageProcessor.resize_image()
        • ImageProcessor.resize_svg()
    • 1.1.6. nikola.log module
      • get_logger()
    • 1.1.7. nikola.metadata_extractors module
      • MetaCondition
        • MetaCondition.compiler
        • MetaCondition.config_bool
        • MetaCondition.config_present
        • MetaCondition.extension
        • MetaCondition.first_line
        • MetaCondition.never
      • MetaPriority
        • MetaPriority.fallback
        • MetaPriority.normal
        • MetaPriority.override
        • MetaPriority.specialized
      • MetaSource
        • MetaSource.filename
        • MetaSource.text
      • check_conditions()
    • 1.1.8. nikola.nikola module
      • Nikola
        • Nikola.GLOBAL_CONTEXT
        • Nikola.MESSAGES
        • Nikola.THEMES
        • Nikola.abs_link()
        • Nikola.apply_shortcodes()
        • Nikola.apply_shortcodes_uuid()
        • Nikola.atom_feed_renderer()
        • Nikola.category_path_to_category_name()
        • Nikola.clean_task_paths()
        • Nikola.file_exists()
        • Nikola.filename_path()
        • Nikola.gen_tasks()
        • Nikola.generic_atom_renderer()
        • Nikola.generic_index_renderer()
        • Nikola.generic_page_renderer()
        • Nikola.generic_post_list_renderer()
        • Nikola.generic_renderer()
        • Nikola.generic_rss_feed()
        • Nikola.generic_rss_renderer()
        • Nikola.get_compiler()
        • Nikola.init_plugins()
        • Nikola.link()
        • Nikola.parse_category_name()
        • Nikola.path()
        • Nikola.plugin_manager
        • Nikola.post_path()
        • Nikola.register_filter()
        • Nikola.register_path_handler()
        • Nikola.register_shortcode()
        • Nikola.rel_link()
        • Nikola.render_template()
        • Nikola.rewrite_links()
        • Nikola.root_path()
        • Nikola.scan_posts()
        • Nikola.slug_path()
        • Nikola.slug_source()
        • Nikola.sort_posts_chronologically()
        • Nikola.template_system
        • Nikola.url_replacer()
    • 1.1.9. nikola.plugin_categories module
      • Command
        • Command.cmd_options
        • Command.doc_description
        • Command.doc_purpose
        • Command.doc_usage
        • Command.execute()
        • Command.name
        • Command.needs_config
      • ConfigPlugin
        • ConfigPlugin.name
      • LateTask
        • LateTask.name
      • MarkdownExtension
        • MarkdownExtension.compiler_name
        • MarkdownExtension.name
      • MetadataExtractor
        • MetadataExtractor.check_requirements()
        • MetadataExtractor.conditions
        • MetadataExtractor.extract_filename()
        • MetadataExtractor.extract_text()
        • MetadataExtractor.map_from
        • MetadataExtractor.name
        • MetadataExtractor.priority
        • MetadataExtractor.requirements
        • MetadataExtractor.source
        • MetadataExtractor.split_metadata_from_text()
        • MetadataExtractor.split_metadata_re
        • MetadataExtractor.supports_write
        • MetadataExtractor.write_metadata()
      • PageCompiler
        • PageCompiler.compile()
        • PageCompiler.compile_string()
        • PageCompiler.config_dependencies
        • PageCompiler.create_post()
        • PageCompiler.default_metadata
        • PageCompiler.demote_headers
        • PageCompiler.extension()
        • PageCompiler.friendly_name
        • PageCompiler.get_compiler_extensions()
        • PageCompiler.get_dep_filename()
        • PageCompiler.get_extra_targets()
        • PageCompiler.metadata_conditions
        • PageCompiler.name
        • PageCompiler.read_metadata()
        • PageCompiler.register_extra_dependencies()
        • PageCompiler.split_metadata()
        • PageCompiler.supports_metadata
        • PageCompiler.supports_onefile
        • PageCompiler.use_dep_file
      • PostScanner
        • PostScanner.scan()
        • PostScanner.supported_extensions()
      • RestExtension
        • RestExtension.compiler_name
        • RestExtension.name
      • SignalHandler
        • SignalHandler.name
      • Task
        • Task.name
      • TaskMultiplier
        • TaskMultiplier.name
        • TaskMultiplier.process()
      • Taxonomy
        • Taxonomy.add_other_languages_variable
        • Taxonomy.always_disable_atom
        • Taxonomy.always_disable_rss
        • Taxonomy.apply_to_pages
        • Taxonomy.apply_to_posts
        • Taxonomy.classification_name
        • Taxonomy.classify()
        • Taxonomy.extract_hierarchy()
        • Taxonomy.get_classification_friendly_name()
        • Taxonomy.get_implicit_classifications()
        • Taxonomy.get_other_language_variants()
        • Taxonomy.get_overview_path()
        • Taxonomy.get_path()
        • Taxonomy.has_hierarchy
        • Taxonomy.include_posts_from_subhierarchies
        • Taxonomy.include_posts_into_hierarchy_root
        • Taxonomy.is_enabled()
        • Taxonomy.minimum_post_count_per_classification_in_overview
        • Taxonomy.more_than_one_classifications_per_post
        • Taxonomy.name
        • Taxonomy.omit_empty_classifications
        • Taxonomy.overview_page_hierarchy_variable_name
        • Taxonomy.overview_page_items_variable_name
        • Taxonomy.overview_page_variable_name
        • Taxonomy.path_handler_docstrings
        • Taxonomy.postprocess_posts_per_classification()
        • Taxonomy.provide_context_and_uptodate()
        • Taxonomy.provide_overview_context_and_uptodate()
        • Taxonomy.recombine_classification_from_hierarchy()
        • Taxonomy.should_generate_atom_for_classification_page()
        • Taxonomy.should_generate_classification_page()
        • Taxonomy.should_generate_rss_for_classification_page()
        • Taxonomy.show_list_as_index
        • Taxonomy.show_list_as_subcategories_list
        • Taxonomy.sort_classifications()
        • Taxonomy.sort_posts()
        • Taxonomy.subcategories_list_template
        • Taxonomy.template_for_classification_overview
        • Taxonomy.template_for_single_list
      • TemplateSystem
        • TemplateSystem.get_deps()
        • TemplateSystem.get_string_deps()
        • TemplateSystem.get_template_path()
        • TemplateSystem.inject_directory()
        • TemplateSystem.name
        • TemplateSystem.render_template()
        • TemplateSystem.render_template_to_string()
        • TemplateSystem.set_directories()
        • TemplateSystem.set_user_engine_factory()
        • TemplateSystem.template_deps()
    • 1.1.10. nikola.post module
      • Post
        • Post.add_dependency()
        • Post.add_dependency_uptodate()
        • Post.alltags
        • Post.author()
        • Post.authors()
        • Post.compile()
        • Post.deps()
        • Post.deps_uptodate()
        • Post.description()
        • Post.destination_path()
        • Post.formatted_date()
        • Post.formatted_updated()
        • Post.fragment_deps()
        • Post.fragment_deps_uptodate()
        • Post.guid()
        • Post.has_math
        • Post.has_oldstyle_metadata_tags
        • Post.has_pretty_url()
        • Post.hyphenate
        • Post.is_draft
        • Post.is_private
        • Post.is_translation_available()
        • Post.is_two_file
        • Post.next_post
        • Post.paragraph_count
        • Post.permalink()
        • Post.post_status
        • Post.prev_post
        • Post.previewimage
        • Post.reading_time
        • Post.register_depfile()
        • Post.remaining_paragraph_count
        • Post.remaining_reading_time
        • Post.save()
        • Post.should_hide_title()
        • Post.should_show_title()
        • Post.source()
        • Post.source_ext()
        • Post.source_link()
        • Post.tags
        • Post.tags_for_language()
        • Post.template_name
        • Post.text()
        • Post.title()
        • Post.translated_base_path()
        • Post.translated_source_path()
        • Post.write_depfile()
        • Post.write_metadata()
    • 1.1.11. nikola.shortcodes module
      • ParsingError
      • apply_shortcodes()
      • extract_shortcodes()
    • 1.1.12. nikola.state module
      • Persistor
        • Persistor.delete()
        • Persistor.get()
        • Persistor.set()
    • 1.1.13. nikola.utils module
      • CustomEncoder
        • CustomEncoder.default()
      • Functionary
      • LocaleBorg
        • LocaleBorg.current_lang
        • LocaleBorg.datetime_formatter
        • LocaleBorg.format_date_in_string()
        • LocaleBorg.formatted_date()
        • LocaleBorg.in_string_formatter
        • LocaleBorg.initialize()
        • LocaleBorg.initialized
        • LocaleBorg.reset()
        • LocaleBorg.set_locale()
      • NikolaPygmentsHTML
        • NikolaPygmentsHTML.wrap()
      • TemplateHookRegistry
        • TemplateHookRegistry.append()
        • TemplateHookRegistry.calculate_deps()
        • TemplateHookRegistry.generate()
      • TranslatableSetting
        • TranslatableSetting.default_lang
        • TranslatableSetting.format()
        • TranslatableSetting.get_lang()
        • TranslatableSetting.lang
        • TranslatableSetting.langformat()
      • TreeNode
        • TreeNode.get_children()
        • TreeNode.get_path()
        • TreeNode.indent_change_after
        • TreeNode.indent_change_before
        • TreeNode.indent_levels
      • adjust_name_for_index_link()
      • adjust_name_for_index_path()
      • adjust_name_for_index_path_list()
      • apply_filters()
      • ask()
      • ask_yesno()
      • bool_from_meta()
      • clean_before_deployment()
      • clone_treenode()
      • config_changed
        • config_changed.configure_task()
      • copy_file()
      • copy_tree()
      • create_redirect()
      • demote_headers()
      • flatten_tree_structure()
      • get_asset_path()
      • get_crumbs()
      • get_displayed_page_number()
      • get_parent_theme_name()
      • get_theme_chain()
      • get_theme_path()
      • get_theme_path_real()
      • get_translation_candidate()
      • get_tzname()
      • html_unescape()
      • indent()
      • join_hierarchical_category_path()
      • load_data()
      • load_messages()
      • makedirs()
      • map_metadata()
      • options2docstring()
      • os_path_split()
      • parse_escaped_hierarchical_category_name()
      • req_missing()
      • rss_writer()
      • slugify()
      • smartjoin()
      • sort_classifications()
      • sort_posts()
      • sys_decode()
      • sys_encode()
      • to_datetime()
      • unslugify()
      • write_metadata()
    • 1.1.14. nikola.winutils module
      • fix_all_git_symlinked()
      • is_file_in_dir()