I'm having some issues adding a custom footer to my Sphinx .html files. I'm using the sphinx_rtd_theme. I've checked this post and tried it (and some of the suggestions in the comments) but to no avail. I'm not sure what I'm missing. Apologies if I haven't posted enough here to actually indicate what is causing the problem. Any help or suggestions is appreciated!
My css theme file has been (poorly) modified by myself (I'm not an HTML/CSS person!) but I don't think that should matter? The only other thing I can think of is maybe I have to do something special when I re-compile the output files. I just use:
make clean html && make html
My conf.py is located at: root/source/conf.py. Here's some excerpts from my conf.py file:
import sphinx_rtd_theme
project = 'Project Name'
copyright = '2021, My Company'
author = 'My Name, Coworker Name'
master_doc = 'Home'
extensions = ["sphinx_rtd_theme", "sphinx.ext.todo"]
todo_include_todos = True
templates_path = ['_templates']
source_suffix = ['.rst']
html4_writer = True
html_theme = 'sphinx_rtd_theme'
# html_theme_path = ['_static']
html_static_path = ['_static']
# html_extra_path = []
html_show_sphinx = True
html_show_copyright = True
html_style = 'css/my_theme.css'
Here's my layout.html file that I have overridden. It's located in the path shown in the comment.
<!-- layout.html
* Place this file in root/source/_templates
* -->
{% extends "!layout.html" %}
{% block extrahead %}
{{super}}
<link href="{{ pathto("_static/my_theme.css", True) }}" rel="stylesheet" type="text/css">
{% endblock %}
{% block extrafooter %}
{{super}}
<div class="footer">
My custom footer just needs to add a single sentance to the existing footer.
</div>
{% endblock %}
Do you want to add a custom footer or replace the default one? in my case, I only need to override the footer.html file instead of layout.html.
Here's what I do that 100% worked for my Sphinx documentation:
create a footer.html in the _template folder of your Sphinx project.
then add this:
{% extends "!footer.html" %}
{%- block contentinfo %}
{{ super }}
<!-- your custom footer here-->
{% endblock %}
be mindful in which block your footer is actually contained within. In my case it's inside contentinfo
So I found a workaround.
1. Copy existing RTD html files
I copied the existing RTD .html files from my virtual environment folder. On my system it was located at the usual place:
.../Miniconda3/envs/my_env_name/Lib/site-packages/sphinx_rtd_theme/
I found the following files:
breadcrumbs.html
footer.html
Layout.html
search.html
searchbox.html
theme.conf
versions.html
I copied those to my working directory for my project:
.../Documentation-repo/Sphinx/root/source/_templates/
2. Edit conf.py file in working directory
I opened my conf.py file and changed the following:
# Add any paths that contain templates here, relative to this directory.
# Uncomment the line below to enable customized template #
#
# templates_path = ['_templates']
to this:
# Add any paths that contain templates here, relative to this directory.
# Uncomment the line below to enable customized template #
#
templates_path = ['_templates']
3. Add new content to footer.html file
I opened footer.html and edited it to add the content I wanted at the bottom. In my case it was as simple as adding my single sentence of changes below the {%- block extrafooter %} {% endblock %} line. Easy. Might not be the perfect solution but it works for what I need.
Related
I have two very similar sections on a jekyll website.
The displayed content change for only some words or resources.
I handle this using 3 files:
One markdown content without Front Matter. This file content the text with if conditions:
# Mardown Content
Here is more info about:
{% if page.section == 'sectionA' %}
[Something About Setion A](/sectionA/something)
{% elsif page.section == "sectionB" %}
[Something About Setion B](/sectionB/somethingelse)
{% endif %}
Two markdown files with front matter including the content
---
layout: myTemplate
section: sectionA/B
title: something
---
{% include content.md %}
I used to have those 3 files in the same directory using {% include_relative content.md %}. This way seems better because the files were in the same directory and the _include folder do not mix up content and html templates.
But my config of jekyll builds also a page for the content file displaying an html page.
Is there a way to prevent serving this html content?
Do you know a better way to handle this?
In _config.yml add :
exclude:
- content.md
This will instruct Jekyll not to process content.md.
Note : I don't get why you cannot put content.md in the _includes folder.
I need to be able to exclude certain files from the build. I am aware I can do this in the config file.
I also need a way to turn off a section of the website in the nav.
So I thought about having a flag in a data file, if it's false do not include a link to the section in the nav.
But how can I also use the same flag to prevent the section from being built?
Or is it easier to specify in config and check this flag in the nav?
To exclude files from builds, add this line to your _config.yml:
keep_files: [folder, "file.ext"]
The folder and the file.ext will be left untouched by Jekyll and will be included on builds.
OR
exclude: ["file.md", "otherfile.html"]
Both files won't be included on you site built by Jekyll at all.
Here:
I also need a way to turn off a section of the website in the nav.
I'm not sure what you meant, but I guess you can probably do that with if statements:
In a post or a page front matter, add a variable indicating the section to exclude:
---
# your front matter settings
foo: bar # variable and value
---
Then, to your template, add:
{% if page.foo %}
<div>this will display</div>
{% endif %}
or
{% if page.foo %}
<div>this will display</div>
{% else %}
<p>this will display when the above doesn't</p>
{% endif %}
Hope to have helped! :)
Seems like a config problem to me. I would put it in the config and have your includes and nav check the config values.
In a Jekyll powered page, I have a set of files located in:
_includes/stuff/
I put those files there so that I can include them in other Markdown pages using:
{% include stuff/example.txt %}
This works as expected.
However, I also want to copy those files to the generated page so that I can link to them and that people can follow those links to download them. But by definition, stuff stored in directories starting with an underscore are not copied by Jekyll.
Another approach also didn't work. I put the files in an own top folder called stuff. This copies the folder to the final site. However, I'm not able to include a file from this folder. It seems include_relative only allows including files below the current one. For example, the following don't work:
{% include_relative stuff/example.txt %}
{% include_relative /stuff/example.txt %}
{% include_relative ../stuff/example.txt %}
Any ideas how I can achieve including and copying at the same time?
This works from index.html
{% include_relative example.txt %} for example.txt
{% include_relative stuff/example.txt %} for stuff/example.txt
{% include_relative /stuff/example.txt %} for stuff/example.txt
stuff/example.txt
class Toto
def dototo
myvar = "toto"
end
end
index.html
{% assign codeurl = "stuff/example.txt" %}
{% highlight ruby %}
{% include_relative {{codeurl}} %}
{% endhighlight %}
link to code
if codeurl == "/stuff/example.txt" this generates a link relative to site root
this may need {{site.baseurl}} prepended if your site is not at the root
of a domain (eg: user.github.io/repository)
link to code
For security reasons, this will not work :
{% include_relative ../stuff/example.txt %}
Just to avoid directory traversal
{% include_relative ../../../../../../../../../../../../etc/pwd %}
If you want to put you files in _includes/stuff you will need to do an include: [ /_includes ] in _config.yml, that will include all files in _includes as static files. Not very clean as you cannot filter subdiretories like include: [ /_includes/stuff ] to import only your stuff files.
Note : a dirty trick allows you to import only _includes/stuff/*.txt but I think it's really dirty.
# _config.yml
include:
- "_includes"
- "stuff"
- "*.txt"
exclude:
- "_includes/*.*"
Im my Jekyll website I need to create an documentation section similar to Original website. However I am not sure how the Docs sections renders. For example, the docs folder, which is located in site root, is filled with documentation .md files. This folder doesn't inculde any index.html file responsible for Layouting of website. The link to that folder is
Doc<span class="show-on-mobiles">s</span><span class="hide-on-mobiles">Documentation</span>
Could someone shed a light on how this section is rendering?
The docs folder includes an index.md, which is rendered as index.html in the final site.
If you look at the YAML front matter of index.md, you'll see this:
---
layout: docs
title: Welcome
next_section: quickstart
permalink: /docs/home/
---
The permalink: /docs/home/ line sets the final URL to {{ site.url }}/docs/home/, even though the actual file is in the /docs folder and the /docs/home folder doesn't even exist.
(for more info about the permalink setting, see Predefined Global Variables in the docs)
So that's where the URL comes from.
Concerning the list of documentation topics (the sidebar on the right):
The YAML front matter of index.md (see above), also contains the line layout: docs.
This refers to /_layouts/docs.html, a layout file.
Inside the layout file, there's the line {% include docs_contents.html %}, which refers to _includes/docs_contents.html, an include file, which contains the following code:
{% for section in site.data.docs %}
<h4>{{ section.title }}</h4>
{% include docs_ul.html items=section.docs %}
{% endfor %}
site.data.docs (in the first line) refers to /_data/docs.yml, a YAML data file.
It looks like this (shortened):
- title: Getting Started
docs:
- home
- quickstart
- installation
- usage
- structure
- configuration
- title: Your Content
docs:
- frontmatter
- posts
- drafts
- pages
- variables
- datafiles
- assets
- migrations
The code inside docs_contents.html loops through the items in the data file, displays the title values ("Getting Started", "Your Content"...) and then includes another include file /_includes/docs_ul.html, passing the list of docs from the data file.
This second include file loops through the list of docs, and does the following for each one:
Step 1:
{% assign item_url = item | prepend:'/docs/' | append:'/' %}
This builds the URL of the page based on the list item. For example, quickstart becomes /docs/quickstart/.
Step 2:
{% if item_url == page.url %}
{% assign c = 'current' %}
{% else %}
{% assign c = '' %}
{% endif %}
This marks the current page (used in the next step) by checking if the URL created in the previous step is equal to the URL of the current page.
Step 3:
{% for p in site.pages %}
{% if p.url == item_url %}
<li class="{{ c }}">{{ p.title }}</li>
{% endif %}
{% endfor %}
This loops all pages in the whole site, until it finds the page with the URL created in the first step.
(to make sure that the URL is equal, all Markdown files in the docs folder have set a permalink in the front-matter, for example permalink: /docs/quickstart/ in quickstart.md)
Then, it outputs a <li> with a link to the page, using the title from the respective Markdown file as the link text.
Plus, the class of the <li> is set to current if it's the current page (see step 2), so the current pae is highlighted in the list:
I use GitHub Pages and created some pages in a sub folder. It seems to be not generating pages I created in sub folder. All other pages work fine. The directory structure is like this:
/
/index.html
/_config.yaml
/_includes
/_layouts
/_posts
/tag
/tag/personal.html
/tag/videos.html
The pages inside the /tag directory are not generated by Jekyll. Also, usually GitHub sends an email if Jekyll build fails, but did not, in this case. Also, if I do any other changes it works, so the build is apparently not failing.
The /tag/personal.html is here:
---
layout: default
title: Tag-personal
permalink: /tag/personal/index.html
tagspec: personal
---
<div id="tagpage">
<h1>Posts tagged personal</h1>
{% include tags.html %}
</div>
and /_includes/tags.html is here:
{% for tag in post.tags %}
{% if tag == page.tagspec %}
{% assign ispostviable = true %}
{% endif %}
{% endfor %}
<ul class="posts">
{% for post in site.posts %}
{% if ispostviable == true %}
<li><a href="{{ post.url }}"></li>
{% endif %}
{% endfor %}
</ul>
PS: I use GitHub Pages and have no access to a Jekyll instance at my development machine (Windows).
Joshua Powell provided step-by-step directions in reply to a similar question on Github.
Edit _config.yml to add the following line (or expand the array, if it exists)
include: ['_pages']
where _pages is the name of the folder in which you wish to keep your files. (This also works for nested folders if you explicitly add them, e.g., ['_pages', '_pages/foo'].)
Move your pages into that folder. (These pages may be HTML, Markdown, or whatever else Jekyll renders when it’s placed in the root folder.)
Give them front matter with an appropiate permalink including a trailing slash, e.g., permalink: "/about/".
I found the culprit. It was that In Jekyll v1.0, absolute permalinks for pages in subdirectories were introduced. Until v1.1, it is opt-in. Starting with v1.1, however, absolute permalinks became opt-out, meaning Jekyll defaults to using absolute permalinks instead of relative permalinks.
The pages were being generated at /tag/tag/personal.html and so on.
There were two solutions:
Specify relative_permalinks: false in _config.yaml
Make permalinks relative to the subdirectory.
I chose the first option.