The experience of making port of readthedocs theme

Share
1

I like this theme(sphinx-rtd-theme) very much, and github pages natively support jekyll, so I made this theme. A little experience is as follows:

Abandon the traditional date + name file format, because it is not good-looking and has no structure to speak of, directly use jekyll’s pages form, so that the produced page has a good structure.

There were a few questions at the beginning:

  1. How to list articles in a specific directory, or even subdirectories, jekyll can list all pages, list files in a specific directory but no solution is found
  2. Sorting of articles
  3. Breadcrumb navigation
  4. pages does not support the previous and next pages
  5. How to combine git data
  6. Is the previous setting feasible without writing the article
  7. The key point is that the liquid language is very weak, or it is not a programming language

After my patient research, I finally got a solution, the idea is as follows:

  1. When listing a specific directory, you can use slashes to divide the path, calculate the length and value to get the directory, of course the file in the directory is the length plus one, which has been resolved

reset all of the dirs and files

get current workspace dirs and files

  1. The sorting of the article can be the file name sort, but such a file structure is really ugly, so the sorting can be sorted by adding a variable to the front of the page, which has been resolved
---
sort: 1
---

# Theme Documentation
  1. Breadcrumb navigation also divides the path into blocks, and then accumulates (for).
    {%- for block in blocks  -%}
                    {%- if forloop.last %}
                        <li>{{ page.title }}</li>
                    {%- else -%}
                        {%- capture href -%}
                            {{ site.baseurl }}/{% for block in blocks limit: forloop.index %}{{ block | append: "/" }}{% endfor %}
                        {%- endcapture %}
                        <li>
                            <a href="{{ href }}">{{ block }}</a></i>
                        </li>
 {%- endif -%}
  1. The prev and next pages of pages can also follow the sorted file list, and the for loop gets the index of the current page, then the previous page is subtracted by 1, and the next page is added by 1, which is resolved
  1. Github pages has the support of the plugin and has been resolved
  2. Do not write the previous settings of the article, you can also use the plugin supported by github pages to automatically obtain the title of the article markdown as the title, which has been resolved
  3. Until now, do you still think that liquid language is not good? Hee hee

Welcome to experience this theme I wrote, This article will continue to be updated, Thanks

1 Like
2

The latest discovery is that if you build the theme in this way, all articles are page, and search data generation is easier

3

Can you elaborate on the benefit of the last comment? Are articles the posts? Why are articles not in the search JSON?
Sorry I not familiar with how the search works

4

Okay, the working principle of search engines is that js loops and regular expressions match json data.

The prerequisite for a successful search is to have all the article data (json format).

The json data obtained in the form of custom tags has serious errors, such as unavailability. The predictable backslash, the json data obtained in this way is the most reliable.

Also, as a document theme, the entire website is not built from posts, all pages,

that is, it has the ability to divide addresses into directories and also has the ability to safely generate search data. Thanks for your attention

5

2000×1460 334 KB