You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _learn/07-evaluating-ssg-themes.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,9 +6,9 @@ image:
6
6
thumbnail: /images/learn/ssg-themes400x225.png
7
7
---
8
8
9
-
Themes for static site generators often provide the advanced user experience features such as navigation, search, and responsive designs for mobile consumption. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables.
9
+
Themes for static site generators often provide advanced user experience features such as navigation, search, and responsive designs for mobile consumption. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables.
10
10
11
-
When researching and selecting a theme, analyze the possibilities for printed outputs, such as PDF or EPUB. Perhaps you need version control for both the output and the source files. The size of your site may mean you need to consider performance gains you can make with the build. Themes are one part of this analysis.
11
+
When researching and selecting a theme, analyze the possibilities for printed outputs, such as PDF or EPUB. Perhaps you need version control for both the output and the source files. The size of your site may mean you need to consider the performance gains you can make with the build. Themes are one part of this analysis.
12
12
13
13
Here's a short list of questions you may want to ask about the theme you use for a static site generator.
14
14
@@ -20,13 +20,13 @@ Advanced admonitions can enable substituting custom text instead of "Note" or "W
For code examples, can you set the exact highlight you want to use, such as JavaScript or Python or Bash? Does the code snippet have a copy icon for copying only the code and not copying a prompt? What about the behavior of the scroll bar for long lines of code examples? Are there line numbers available? Can you highlight or emphasize certain lines to convey meaning? How about captions on the code block, similar to captions on figures?
23
+
For code examples, can you set the exact highlight you want to use, such as JavaScript or Python? Does the code snippet have a copy icon for copying only the code and not copying a prompt? What about the behavior of the scroll bar for long lines of code examples? Are there line numbers available? Can you highlight or emphasize certain lines to convey meaning? How about captions on the code block, similar to captions on figures?
24
24
25
25
## Comments or forums integration
26
26
Which comment engines are supported? Do they work with the comment systems other organizations use in your company or group?
27
27
28
28
## Customization
29
-
How straightforward is it to add your logo or a header that's common to multiple web sites? Can you learn how to maintain the theme's customizations yourself or will you need to rely on a web developer for maintenance and any enhancements such as adding a version drop-down list? For example, the Jekyll theme "Minimal Mistakes" is "skinnable," meaning you can [configure various color variations](https://mmistakes.github.io/minimal-mistakes/docs/configuration/) for that theme.
29
+
How straightforward is it to add your logo or a header that's common to multiple websites? Can you learn how to maintain the theme's customizations yourself or will you need to rely on a web developer for maintenance and any enhancements such as adding a version drop-down list? For example, the Jekyll theme "Minimal Mistakes" is "skinnable," meaning you can [configure various color variations](https://mmistakes.github.io/minimal-mistakes/docs/configuration/) for that theme.
30
30
31
31
## Images
32
32
Are images automatically resized when looking at them on a mobile browser or resized browser window? Are alt tags and captions considered in the design?
@@ -35,31 +35,31 @@ Are images automatically resized when looking at them on a mobile browser or res
35
35
When translations are available, are they simple to get to? Does the theme itself have the ability to be localized, such as for the search form or navigation elements, can the labels used in the theme be localized?
36
36
37
37
## Navigation and configuration possibilities
38
-
Does the theme have a sidebar, breadcrumbs, and an in-page table of contents available? Can you turn on or off each based on the page layout or page template or whether the person is using a mobile browser or tablet?
38
+
Does the theme have a sidebar, breadcrumbs, and an in-page table of contents available? Can you turn on or off each based on the page layout or whether the person is using a mobile browser or tablet?
39
39
40
40
Do you want to have Previous and Next buttons on each page, so that someone can go through a series of pages in order?
41
41
42
42
## Responsive and mobile design
43
43
Does the theme use thoughtful navigation and search when on a small screen?
44
44
45
-
Can your readers get to the Contents fairly easily and expand and contract, even when on a mobile phone or tablet? Check how the search experience works when using a smaller screen. Most of the built-into-the-browser developer tool kits, such as the Chrome Developer Tool, lets you preview the site experience on a simulated smaller screen.
45
+
Can your readers get to the Contents fairly easily and expand and contract, even when on a mobile phone or tablet? Check how the search experience works when using a smaller screen. Most of the built-into-the-browser developer tool kits, such as the Chrome Developer Tool, let you preview the site experience on a simulated smaller screen.
46
46
47
47

48
48
49
49
## Search
50
-
Is the search form in a prominent location and if needed, can you customize the them to place the search form somewhere else on the page? Does the search work on mobile devices with readable results? Can the result list also be styled?
50
+
Is the search form in a prominent location and if needed, can you customize the theme to place the search form somewhere else on the page? Does the search work on mobile devices with readable results? Can the result list also be styled? Can you add weighting to certain search results so that those appear at the top of the results list?
51
51
52
52
## Social media support
53
53
If you want Twitter cards for your documentation pages, are they available through the theme? Which social media sites can you link to from each page?
54
54
55
55
## Tables
56
-
Do tables work on different browsers? If PDF or epub is another output option, do the tables still work on a particular page size or do you need to adjust how tables are made in the source file itself for good results in the output?
56
+
Do tables work on different browsers? If PDF or epub is another output option, do the tables still work on particular page sizes or do you need to adjust how tables are made in the source file itself for good results in the output?
57
57
58
58
## Theme updates
59
59
How easy is it to upgrade the theme files? Can you make regular updates through a version-control system and know exactly which theme you have in use?
60
60
61
61
## Versions
62
-
Many themes do not have a version picker by default. You might want a drop-down list or navigation that could include version. The Sphinx Read the Docs theme does have one and it works great. For Jekyll, look at the [versions-jekyll repository](https://github.com/justwriteclick/versions-jekyll) to see a couple of implementation ideas.
62
+
Many themes do not have a version picker by default. You might want a drop-down list or navigation that could include the version. The Sphinx Read the Docs theme does have one and it works great. For Jekyll, look at the [versions-jekyll repository](https://github.com/justwriteclick/versions-jekyll) to see a couple of implementation ideas.
0 commit comments