diff --git a/_posts/10-evaluating-ssg-themes.md b/_learn/07-evaluating-ssg-themes.md similarity index 83% rename from _posts/10-evaluating-ssg-themes.md rename to _learn/07-evaluating-ssg-themes.md index bb77203e..b5f4fa19 100644 --- a/_posts/10-evaluating-ssg-themes.md +++ b/_learn/07-evaluating-ssg-themes.md @@ -1,11 +1,13 @@ --- title: "Evaluating Static Site Generator themes" image: - path: /images/so-simple-sample-image-4.jpg - thumbnail: /images/site-logo.png + path: /images/learn/ssg-themes.png + thumbnail: /images/learn/ssg-themes400x225.png --- -Themes for static site generators often provide the advanced user experience features such as search. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables. What about printed outputs, such as PDF? Or versions for the output and the source? Any performance gains you can make with the builds themselves? Themes are one part of this analysis. +Themes for static site generators often provide the advanced user experience features such as search. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables. + +What about printed outputs, such as PDF? Or versions for the output and the source? Any performance gains you can make with the builds themselves? Themes are one part of this analysis. Here's a short list of questions you may want to ask about the theme you use for a static site generator. @@ -16,7 +18,7 @@ Are there designs for output of levels of admonition, such as warning, informati 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? ## Comment engines -Which comment engines are supported and do they work with what other organizations use in your company or group? +Which comment engines are supported? Do they work with what other organizations use in your company or group? ## Customization 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. @@ -28,7 +30,7 @@ Are images automatically resized when looking at them on a mobile browser or res 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? ## Navigation and configuration possibilities -Does the theme have a sidebar, breadcrumbs, and an in-page table of contents? 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? +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? ## Responsive and mobile design Does the theme use thoughtful navigation and search when on a small screen? @@ -37,12 +39,12 @@ Does the theme use thoughtful navigation and search when on a small screen? Is the search form in a prominent location and if needed, can you move the search form on the page? Does the search work on mobile devices with readable results? Can the result list also be styled? ## Social media support -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 documentation page? +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? ## Tables 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? -## Theme Updates +## Theme updates 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? ## Versions diff --git a/_posts/11-evaluating-table-layouts.md b/_learn/08-evaluating-table-layouts.md similarity index 88% rename from _posts/11-evaluating-table-layouts.md rename to _learn/08-evaluating-table-layouts.md index 0c079be9..c3e988c6 100644 --- a/_posts/11-evaluating-table-layouts.md +++ b/_learn/08-evaluating-table-layouts.md @@ -1,10 +1,12 @@ --- title: "Evaluating table layouts and formatting" image: - path: /images/so-simple-sample-image-4.jpg - thumbnail: /images/site-logo.png + path: /images/learn/table-layout.png + thumbnail: /images/learn/table-layout400x225.png --- +Table layout can be an annoying and difficult aspect of using simple markdown as documentation source. That said, when using Markdown or RST tables you can compare changes to simple tables more easily during reviews. + One of the most helpful tools when creating tables for Markdown or RST is the Tables Generator at https://www.tablesgenerator.com/markdown_tables. You can draw tables or paste table data and then render the ASCII-based output for pasting into your document source file. For example, here is an empty five-column table in Markdown, ready for you to insert cell data and spaces. diff --git a/_posts/14-ssg-search-implementations.md b/_learn/09-ssg-search-implementations.md similarity index 91% rename from _posts/14-ssg-search-implementations.md rename to _learn/09-ssg-search-implementations.md index e5926119..093ef6dc 100644 --- a/_posts/14-ssg-search-implementations.md +++ b/_learn/09-ssg-search-implementations.md @@ -1,8 +1,8 @@ --- -title: "Static Site Generator search options" +title: "Evaluating Static Site Generator search options" image: - path: /images/so-simple-sample-image-4.jpg - thumbnail: /images/site-logo.png + path: /images/learn/ssg-search-options.png + thumbnail: /images/learn/ssg-search-options400x225.png --- Most static site generators provide a browser-side search capability, where the list of indexed keywords for search are built at the same time as the output. Learn more about considerations for each SSG in the following sections. diff --git a/_posts/00-github-for-docs-files.md b/_posts/00-github-for-docs-files.md index 28703599..a6a5afe6 100644 --- a/_posts/00-github-for-docs-files.md +++ b/_posts/00-github-for-docs-files.md @@ -12,7 +12,7 @@ Learning GitHub or any source control system backed by `git` for documentation s You can learn how to sign up for a GitHub account and pricing plans on [help.github.com](https://help.github.com/articles/signing-up-for-a-new-github-account/). -You can do all these docs-as-code tutorials with a free GitHub account. +You can do all these docs-as-code tutorials with a free GitHub account. I recommend using SSH keys rather than entering your password for each `git` command that requires authentication. Read about [Connecting to GitHub with SSH](https://help.github.com/articles/connecting-to-github-with-ssh/) in the GitHub user documentation. ## Learn basic Terminal and Git Bash commands diff --git a/_posts/08-templating.md b/_posts/10-templating.md similarity index 100% rename from _posts/08-templating.md rename to _posts/10-templating.md diff --git a/_posts/12-print-pdf-epub-output.md b/_posts/11-print-pdf-epub-output.md similarity index 100% rename from _posts/12-print-pdf-epub-output.md rename to _posts/11-print-pdf-epub-output.md diff --git a/_posts/13-ssg-performance.md b/_posts/12-ssg-performance.md similarity index 100% rename from _posts/13-ssg-performance.md rename to _posts/12-ssg-performance.md diff --git a/images/learn/ssg-search-options.png b/images/learn/ssg-search-options.png new file mode 100644 index 00000000..7a431306 Binary files /dev/null and b/images/learn/ssg-search-options.png differ diff --git a/images/learn/ssg-search-options400x225.png b/images/learn/ssg-search-options400x225.png new file mode 100644 index 00000000..4e57b337 Binary files /dev/null and b/images/learn/ssg-search-options400x225.png differ diff --git a/images/learn/ssg-themes.png b/images/learn/ssg-themes.png new file mode 100644 index 00000000..93cb3a98 Binary files /dev/null and b/images/learn/ssg-themes.png differ diff --git a/images/learn/ssg-themes400x225.png b/images/learn/ssg-themes400x225.png new file mode 100644 index 00000000..dce79a09 Binary files /dev/null and b/images/learn/ssg-themes400x225.png differ diff --git a/images/learn/table-layout.png b/images/learn/table-layout.png new file mode 100644 index 00000000..90b91cfa Binary files /dev/null and b/images/learn/table-layout.png differ diff --git a/images/learn/table-layout400x225.png b/images/learn/table-layout400x225.png new file mode 100644 index 00000000..e7e34c87 Binary files /dev/null and b/images/learn/table-layout400x225.png differ