diff --git a/_data/sidebars/mydoc_sidebar.yml b/_data/sidebars/mydoc_sidebar.yml index cd5a2eb..5e0803e 100644 --- a/_data/sidebars/mydoc_sidebar.yml +++ b/_data/sidebars/mydoc_sidebar.yml @@ -1,9 +1,9 @@ # This is your sidebar TOC. The sidebar code loops through sections here and provides the appropriate formatting. entries: -- title: Mydoc - product: Mydoc - version: version 5.0 +- title: sidebar + product: Jekyll Doc Theme + version: 5.0 subcategories: - title: @@ -23,6 +23,14 @@ entries: output: web, pdf items: + - title: 5.0 Release notes + url: /mydoc_release_notes_50/ + output: web, pdf + + - title: Get started + url: / + output: web, pdf + - title: Introduction url: /mydoc_introduction/ output: web, pdf @@ -31,10 +39,6 @@ entries: url: /mydoc_supported_features/ output: web, pdf - - title: Get started - url: /mydoc_getting_started/ - output: web, pdf - - title: About the theme author url: /mydoc_about/ output: web, pdf @@ -139,6 +143,10 @@ entries: url: /mydoc_commenting_on_files/ output: web, pdf +# - title: Git collaboration +# url: /mydoc_git_collaboration/ +# output: web, pdf + - title: Publishing output: web, pdf @@ -191,6 +199,10 @@ entries: url: /mydoc_glossary/ output: web, pdf + - title: FAQ layout + url: /mydoc_faq_layout/ + output: web, pdf + - title: Troubleshooting output: web, pdf @@ -214,6 +226,7 @@ entries: thirdlevel: - title: Tag archive pages + output: web thirdlevelitems: - title: Formatting pages @@ -238,4 +251,8 @@ entries: - title: Collaboration pages url: /tag_collaboration/ + output: web + + - title: Troubleshooting pages + url: /tag_troubleshooting/ output: web \ No newline at end of file diff --git a/_data/sidebars/product1_sidebar.yml b/_data/sidebars/product1_sidebar.yml index 17df9bd..b3647de 100644 --- a/_data/sidebars/product1_sidebar.yml +++ b/_data/sidebars/product1_sidebar.yml @@ -4,7 +4,7 @@ entries: - title: Sidebar product: Product1 - version: version 1.0 + version: 1.0 subcategories: - title: diff --git a/_data/sidebars/product2_sidebar.yml b/_data/sidebars/product2_sidebar.yml index 8b5572d..a8a08cb 100644 --- a/_data/sidebars/product2_sidebar.yml +++ b/_data/sidebars/product2_sidebar.yml @@ -3,7 +3,7 @@ entries: - title: Product2 product: Product2 - version: version 1.0 + version: 1.0 subcategories: - title: diff --git a/_data/sidebars/tags_sidebar.yml b/_data/sidebars/tags_sidebar.yml index da92e0b..6e6e429 100644 --- a/_data/sidebars/tags_sidebar.yml +++ b/_data/sidebars/tags_sidebar.yml @@ -4,33 +4,51 @@ entries: product: Tags version: all products levels: one + output: web subcategories: - title: News + output: web items: - title: News url: /news/ + output: web - title: News archive url: /news_archive/ + output: web - title: Tags + output: web items: - title: Collaboration url: /tag_collaboration/ + output: web - title: Content Types url: /tag_content_types/ + output: web - title: Formatting url: /tag_formatting/ + output: web - title: Getting started url: /tag_getting_started/ + output: web - title: Mobile url: /tag_mobile/ + output: web - title: Navigation url: /tag_navigation/ + output: web - title: News url: /tag_news/ + output: web - title: Publishing url: /tag_publishing/ + output: web - title: Single sourcing url: /tag_single_sourcing/ + output: web - title: Special layouts - url: /tag_special_layouts/ \ No newline at end of file + url: /tag_special_layouts/ + output: web + - title: Troubleshooting + url: /tag_troubleshooting/ + output: web \ No newline at end of file diff --git a/_data/topnav.yml b/_data/topnav.yml index e5a9aff..9313ddb 100644 --- a/_data/topnav.yml +++ b/_data/topnav.yml @@ -24,7 +24,7 @@ topnav_dropdowns: external_url: http://idratherbewriting.com/category-jekyll/ - title: Products items: - - title: Theme instructions + - title: Jekyll Documentation Theme url: /mydoc_introduction/ - title: Product 1 url: /p1_landing_page/ diff --git a/_includes/head.html b/_includes/head.html index 08784b9..4951c39 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -12,7 +12,7 @@ - + diff --git a/_includes/sidebar.html b/_includes/sidebar.html index e69de29..0c0cca9 100644 --- a/_includes/sidebar.html +++ b/_includes/sidebar.html @@ -0,0 +1,56 @@ +{% include custom/sidebarconfigs.html %} + +
{{sidebar[0].product}} {{sidebar[0].version}}
+ + + + + \ No newline at end of file diff --git a/_includes/toc.html b/_includes/toc.html index 1d30ae3..067141a 100644 --- a/_includes/toc.html +++ b/_includes/toc.html @@ -18,6 +18,4 @@ $('#toc').on('click', 'a', function() { }); -{% unless page.toc == false %}
-{% endunless %} \ No newline at end of file diff --git a/_layouts/default.html b/_layouts/default.html index 5e6ebdf..b4873e2 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -62,62 +62,7 @@
- {% include custom/sidebarconfigs.html %} - {{sidebar[0].product}} - {{sidebar[0].version}} - -
- - - + {% include sidebar.html %}
{{content}} diff --git a/css/customstyles.css b/css/customstyles.css index 77c384b..b3a8946 100644 --- a/css/customstyles.css +++ b/css/customstyles.css @@ -72,16 +72,16 @@ body { .breadcrumb > .active {color: #777 !important;} /* make room for the nav bar */ -h1[id], -h2[id], -h3[id], -h4[id], -h5[id], -h6[id], -dt[id]{ - padding-top: 60px; - margin-top: -40px -} +/*h1[id],*/ +/*h2[id],*/ +/*h3[id],*/ +/*h4[id],*/ +/*h5[id],*/ +/*h6[id],*/ +/*dt[id]{*/ + /*padding-top: 60px; */ + /*margin-top: -40px*/ +/*}*/ body h1 {margin-top:40px;} @@ -395,8 +395,6 @@ text-decoration: none; } ul#mysidebar { - margin-top:40px; - border-radius:0px; } @@ -1000,4 +998,14 @@ span.label.label-default { span.label.label-primary { background-color: #f0ad4e; } - .col-lg-12 .nav li a {background-color: white} \ No newline at end of file +.col-lg-12 .nav li a {background-color: white} + +div.sidebarTitle { + margin-top:40px; + font-weight:normal; + font-size:130%; + color: #ED1951; + margin-bottom:10px; + margin-left: 5px; + +} diff --git a/css/theme-blue.css b/css/theme-blue.css index 1b232e9..8719bd6 100644 --- a/css/theme-blue.css +++ b/css/theme-blue.css @@ -86,4 +86,8 @@ body.print h4 {color: #679DCE !important; font-size:14px; font-style: italic !im .anchorjs-link:hover { color: #216f9b; +} + +div.sidebarTitle { + color: #015CAE; } \ No newline at end of file diff --git a/css/theme-green.css b/css/theme-green.css index e1bdafc..f1c3f24 100644 --- a/css/theme-green.css +++ b/css/theme-green.css @@ -82,4 +82,8 @@ body.print h4 {color: #679DCE !important; font-size:14px; font-style: italic;} .anchorjs-link:hover { color: #4f7233; +} + +div.sidebarTitle { + color: #E50E51; } \ No newline at end of file diff --git a/index.html b/index.html deleted file mode 100644 index 9ebbdd9..0000000 --- a/index.html +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Introduction -tags: [getting_started] -sidebar: home_sidebar -toc: none ---- - - diff --git a/mydoc/mydoc_getting_started.md b/index.md similarity index 90% rename from mydoc/mydoc_getting_started.md rename to index.md index 0af4c43..d90fd71 100644 --- a/mydoc/mydoc_getting_started.md +++ b/index.md @@ -1,18 +1,13 @@ --- title: Getting started tags: [getting_started] -keywords: start, introduction, begin, install, build, hello world, -last_updated: March 20, 2016 -summary: "To get started with this theme, first make sure you have all the prerequisites in place; then build the theme following the sample build commands." -series: "Getting Started" sidebar: mydoc_sidebar -permalink: /mydoc_getting_started/ --- ## Getting up and running -To get up and running with this theme, make sure you can build a vanilla jekyll site first. See the [Jekyll docs](http://jekyllrb.com/). +To get up and running with this theme, make sure you can build a vanilla jekyll site first. See the [Jekyll docs](http://jekyllrb.com/). If you're in Windows, you might want to [install Jekyll using Chocolately](https://www.google.com/search?q=install+jekyll+using+chocolately). @@ -80,12 +75,12 @@ Note that your sidebar can only have 2 levels. Given that each product has its o The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown: ```yaml - - title: Overview - output: web, pdf - items: - - title: Mydoc home - url: /mydoc_landing_page/ - output: web +- title: Overview +output: web, pdf +items: +- title: Mydoc home +url: /mydoc_landing_page/ +output: web ``` Each heading must contain a title and output property. Each item must contain a title, url, and output property. @@ -97,18 +92,18 @@ The YAML syntax depends on exact spacing, so make sure you follow the pattern sh To accommodate the title page and table of contents in PDF outputs, each product sidebar must list these pages before any other: ```yaml - - title: - output: pdf - type: frontmatter - items: - - title: - url: /titlepage/ - output: pdf - type: frontmatter - - title: - url: /tocpage/ - output: pdf - type: frontmatter +- title: +output: pdf +type: frontmatter +items: +- title: +url: /titlepage/ +output: pdf +type: frontmatter +- title: +url: /tocpage/ +output: pdf +type: frontmatter ``` Leave the output as `output: pdf` so that they don't appear in the web output. @@ -135,7 +130,7 @@ For titles, surrounding the title in quotes is optional, but if you have a colon Keywords get populated into the metadata of the page for SEO. -Tags must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll wont auto-create these tag files.) +Tags must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll wont auto-create these tag files.) ``` If you don't want the mini-TOC to show on a page (such as for the homepage or landing pages), add `toc: none` in the frontmatter. @@ -148,7 +143,7 @@ For external URLs, use `external_url` in the item property, as shown in the exam Note that the topnav has two sections: topnav and topnav_dropdowns. The topnav section contains single links, while the topnav_dropdowns section contains dropdown menus. The two sections are independent of each other. -## Generating PDF +## Generating PDF If you want to generate PDF, you'll need a license for [Prince XML](http://www.princexml.com/). You will also need to [install Prince](http://www.princexml.com/doc/installing/). You can generate PDFs by product (but not for every product on the site combined together into one massive PDF). Prince will work even without a license, but it will imprint a small Prince image on the first page. @@ -158,7 +153,7 @@ See the section on [generating PDFs](mydoc_generating_pdfs) for more details abo ## Blogs / News -For blog posts, create your markdown files in the \_posts folder following the sample formats. Post file names always begin with the date (YYYY-MM-DD-title). +For blog posts, create your markdown files in the \_posts folder following the sample formats. Post file names always begin with the date (YYYY-MM-DD-title). The news/news.html file displays the posts, and the news_archive.html file shows a yearly history of posts. In documentation, you might use the news to highlight product features outside of your documentation, or to provide release notes and other updates. @@ -173,5 +168,3 @@ For other details in working with the theme, see the various sections in the sid - - diff --git a/mydoc/mydoc_faq.html b/mydoc/mydoc_faq.html index 47eee60..6642fe5 100644 --- a/mydoc/mydoc_faq.html +++ b/mydoc/mydoc_faq.html @@ -1,17 +1,17 @@ --- title: FAQ layout +permalink: /mydoc_faq_layout/ +sidebar: mydoc_sidebar tags: [special_layouts] keywords: frequently asked questions, FAQ, question and answer, collapsible sections, expand, collapse -last_updated: March 20, 2016 +last_updated: November 30, 2015 summary: "You can use an accordion-layout that takes advantage of Bootstrap styling. This is useful for an FAQ page." -sidebar: mydoc_sidebar -permalink: /mydoc_faq/ +toc: none --- -If you want to use an FAQ format, use the syntax shown on the faq.html page. Rather than including code samples here (which are bulky with a lot of nested div tags), just look at the source in the mydoc_faq.html theme file. +

If you want to use an FAQ format, use the syntax shown on the faq.html page. Rather than including code samples here (which are bulky with a lot of nested div tags), just look at the source in the mydoc_faq.html theme file.

- -
+

@@ -129,6 +129,6 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat

-
- +
+ \ No newline at end of file diff --git a/mydoc/mydoc_install_dependencies.md b/mydoc/mydoc_install_dependencies.md index e6c5a79..a492249 100644 --- a/mydoc/mydoc_install_dependencies.md +++ b/mydoc/mydoc_install_dependencies.md @@ -1,17 +1,14 @@ --- title: Adding all project dependencies -tags: [getting-started] +tags: [getting-started, troubleshooting] keywords: -summary: "" +summary: "You want to be sure that you have all the required gems and other utilities on your computer to make the project run. Jekyll runs on Ruby, and there are various plugins for Ruby that enable different functionality. These Ruby plugins are referred to as gems, and you install the gems you need for your projects." sidebar: mydoc_sidebar permalink: /mydoc_install_dependencies/ --- -You want to be sure that you have all the required gems and other utilities on your computer to make the project run. Jekyll runs on Ruby, and there are various plugins for Ruby that enable different functionality. These Ruby plugins are referred to as gems, and you install the gems you need for your projects. - To manage the various gems and their versions needed for your project, you can use a package manager called Bundler. Many projects will have a gemfile in their project that lists the gems required for the project. You then run Bundler in order to automatically install the required gems and any dependencies for those gems on your machine. - ## RubyGems Make sure you have RubyGems. This should be installed by default on Mac. diff --git a/mydoc/mydoc_iterm_profiles.md b/mydoc/mydoc_iterm_profiles.md index 520e4a9..822d3fd 100644 --- a/mydoc/mydoc_iterm_profiles.md +++ b/mydoc/mydoc_iterm_profiles.md @@ -3,15 +3,14 @@ title: iTerm profiles tags: [publishing] keywords: iterm, terminal, build shortcuts, mac last_updated: March 20, 2016 -summary: "Set up profiles in iTerm to facilitate the build process with just a few clicks. This can make it a lot easier to quickly build multiple outputs." +summary: "You can set up profiles in iTerm to facilitate the build process with just a few clicks. This can make it a lot easier to quickly build multiple outputs." sidebar: mydoc_sidebar permalink: /mydoc_iterm_profiles/ --- - ## About iTerm profiles -When you're working with tech docs, a lot of times you're single sourcing multiple outputs. It can be a hassle to fire up each one of these outputs using the build files containing the shell scripts. Instead, it's easier to configure iTerm with profiles that initiate the scripts. +When you're working with tech docs, a lot of times you have builds that push files onto different servers, or that build the content for different environments. It can be a hassle to type out these commands each time. Instead, it's easier to configure iTerm with profiles that initiate the scripts. ## Set up profiles @@ -22,7 +21,7 @@ When you're working with tech docs, a lot of times you're single sourcing multip 5. In the **Send text at start** field, type the command for the build script, such as this: ``` - jekyll serve --config configs/config_designers.yml + JEKYLL_ENV=production jekyll serve ``` Leave the Login shell option selected. @@ -38,4 +37,4 @@ Here's an example: 1. In iTerm, make sure the Toolbar is shown. Go to **View > Toggle Toolbar**. 2. Click the **New** button and select your profile. -{{site.data.alerts.tip}} When you're done with the session, make sure to click **Ctrl+C**.{{site.data.alerts.end}} \ No newline at end of file +{{site.data.alerts.tip}} When you're done with the session, make sure to click Ctrl+C.{{site.data.alerts.end}} \ No newline at end of file diff --git a/mydoc/mydoc_kb_layout.md b/mydoc/mydoc_kb_layout.md index 6699d99..4ba1984 100644 --- a/mydoc/mydoc_kb_layout.md +++ b/mydoc/mydoc_kb_layout.md @@ -8,38 +8,92 @@ sidebar: mydoc_sidebar permalink: /mydoc_kb_layout/ --- -
-
Getting Started
-
Navigation
-
single_sourcing
+
+

Knowledge Base Categories

+
+
+
+
+ + + + +
+
+

Getting started

+

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

+ Learn More +
+
+
+
+
+
+ + + + +
+
+

Navigation

+

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

+ Learn More +
+
+
+
+
+
+ + + + +
+
+

Single sourcing

+

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

+ Learn More +
+
+
+
+
+
+ + + + +
+
+

Formatting

+

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

+ Learn More +
+
+
-

 

-
-
Publishing
-
Special layouts
-
Formatting
-
- + + ## Generating a list of all pages with a certain tag If you don't want to link to a tag archive index, but instead want to list all pages that have a certain tag, you could use this code: -{% raw %} ```html -Getting started pages: +{% raw %}Getting started pages: +{% endraw %} ``` -{% endraw %} + +Here's the result: Getting started pages: @@ -48,7 +102,7 @@ Getting started pages: {% for page in sorted_pages %} {% for tag in page.tags %} {% if tag == "getting_started" %} -
  • {{page.title}}
    • +
  • {{page.title}}
    • {% endif %} {% endfor %} {% endfor %} diff --git a/mydoc/mydoc_no_password_prompts_scp.md b/mydoc/mydoc_no_password_prompts_scp.md index a3c21c0..0703809 100644 --- a/mydoc/mydoc_no_password_prompts_scp.md +++ b/mydoc/mydoc_no_password_prompts_scp.md @@ -1,126 +1,129 @@ --- title: Getting around the password prompts in SCP sidebar: mydoc_sidebar +tags: [publishing, troubleshooting] permalink: /mydoc_no_password_prompts_scp/ +summary: "You can publish your docs via SSH through a Terminal window or more likely, via a shell script that you simply execute as part of the publishing process. However, you will be prompted for your password with each file transfer unless you configure passwordless SSH. The basic process for setting up password less SSH is to create a key on your own machine that you also transfer to the remote machine. When you use the SCP command, the remote machine checks that you have the authorized key and allows access without a password prompt." --- -You can publish your docs via SSH through a Terminal window or more likely, via a shell script that you simply execute as part of the publishing process. However, you will be prompted for your password with each file transfer unless you configure passwordless SSH. +## Get rid of password prompts + -The basic process for setting up password less SSH is to create a key on your own machine that you also transfer to the remote machine. When you use the SCP command, the remote machine checks that you have the authorized key and allows access without a password prompt. - To remove the password prompts when connecting to servers via SSH: 1. On your local machine, go to your .ssh directory: -``` -cd ~/.ssh -``` + ``` + cd ~/.ssh + ``` + + Note that any directory that starts with a dot, like .ssh, is hidden. You can view hidden folders by enabling them on your Mac. See [this help topic](http://ianlunn.co.uk/articles/quickly-showhide-hidden-files-mac-os-x-mavericks/). Additionally, when you look at the files in a directory, use ls -a instead of just ls to view the hidden files. + + If you don't have an .ssh directory, create one with `mkdir .ssh`. + +2. Create a new key inside your .ssh directory: + + ``` + ssh-keygen -t rsa + ``` + +3. Press **Enter**. When prompted about "Enter file in which to save the key ...", press ```Enter``` again. + + This will create a file called id_rsa.pub (the key) and id_rsa (your identification) in this .ssh folder. -Note that any directory that starts with a dot, like .ssh, is hidden. You can view hidden folders by enabling them on your Mac. See [this help topic](http://ianlunn.co.uk/articles/quickly-showhide-hidden-files-mac-os-x-mavericks/). Additionally, when you look at the files in a directory, use ls -a instead of just ls to view the hidden files. + When prompted for a passphrase for the key, just leave it empty and press **Enter** twice. You should see something like this: + + ``` + tjohnson-mbpr13:.ssh tjohnson$ ssh-keygen -t rsa + Generating public/private rsa key pair. + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + Your identification has been saved in /Users/tjohnson/.ssh/id_rsa. + Your public key has been saved in /Users/tjohnson/.ssh/id_rsa.pub. + The key fingerprint is: + 9a:8f:b5:495:39:78:t5:dc:19:d6:29:66:02:e8:02:a0 tjohnson@tjohnson-mbpr13.local + ``` + + The key's randomart image is: + + ``` + +--[ RSA 2048]----+ + |. | + |+ | + |E | + |o. . | + |.. = o S | + |.&^ + 7i = o | + | = B . | + | o O + | + | *.o | + +-----------------+ + ``` + + As you can see, RSA draws a picture for you. Take a screenshot of the picture, print it out, and put it up on your fridge. + +4. Open up another terminal window (in iTerm, open another tab), and SSH in to your remote server: + + ``` + ssh @remoteserver.com + ``` + +5. Change `` to your actual username, such as tjohnson. + + When you connect, you'll be prompted for your password. + + When you connect, by default you are routed to the personal folder on the directory. For example, `/home/remoteserver/`. To see this directory, type `pwd` (or `dir` on Windows). + +6. Create a new directory called .ssh on remoteserver.com server inside the `/home/remoteserver/` directory. + + ``` + mkdir -p .ssh + ``` + + You can ensure that it's there with this command: + + ``` + ls -a + ``` + + Without the -a, the hidden directory won't be shown. + +7. Open another Terminal window and browse to /Users//.ssh on your local machine. + + ``` + cd ~/.ssh + ``` + +8. Copy the id_rsa.pub from the /.ssh directory on your local machine to the /home/remoteserver//.ssh directory on the remoteserver server: + + ``` + scp id_rsa.pub @yourserver.com:/home/remoteserver//.ssh + ``` + +9. Switch back into your terminal window that is connected to remoteserver.com, change directory to the .ssh directory, and rename the file from id_rsa.pub to `authorized_keys` (without any file extension): + + ``` + mv id_rsa.pub authorized_keys + ``` + +10. Change the file permissions to 700: + + ``` + chmod 700 authorized_keys + ``` + + Now you should be able to SSH onto remoteserver without any password prompts. -If you don't have an .ssh directory, create one with `mkdir .ssh`. - -Create a new key inside your .ssh directory: - -``` -ssh-keygen -t rsa -``` - -Press Enter. When prompted about "Enter file in which to save the key ...", press Enter again. - -This will create a file called id_rsa.pub (the key) and id_rsa (your identification) in this .ssh folder. - -When prompted for a passphrase for the key, just leave it empty and press Enter twice. You should see something like this: - - -tjohnson-mbpr13:.ssh tjohnson$ ssh-keygen -t rsa -Generating public/private rsa key pair. -Enter passphrase (empty for no passphrase): -Enter same passphrase again: -Your identification has been saved in /Users/tjohnson/.ssh/id_rsa. -Your public key has been saved in /Users/tjohnson/.ssh/id_rsa.pub. -The key fingerprint is: -9a:8f:b5:495:39:78:t5:dc:19:d6:29:66:02:e8:02:a0 tjohnson@tjohnson-mbpr13.local -The key's randomart image is: - -``` -+--[ RSA 2048]----+ -|. | -|+ | -|E | -|o. . | -|.. = o S | -|.&^ + 7i = o | -| = B . | -| o O + | -| *.o | -+-----------------+ -``` -Icon -As you can see, RSA draws a picture for you. Take a screenshot of the picture, print it out, and put it up on your fridge. - -Open up another terminal window (in iTerm, open another tab), and SSH in to your remote server: - -``` -ssh @remoteserver.com -``` - -Change `` to your actual username, such as tjohnson. - -When you connect, you'll be prompted for your password. - -When you connect, by default you are routed to the personal folder on the directory. For example, `/home/remoteserver/`. To see this directory, type `pwd`. - -Create a new directory called .ssh on remoteserver.com server inside the `/home/remoteserver/` directory. - -``` -mkdir -p .ssh -``` - -You can ensure that it's there with this command: - -``` -ls -a -``` - -Without the -a, the hidden directory won't be shown. - -Open another Terminal window and browse to /Users//.ssh on your local machine. - -``` -cd ~/.ssh -``` - -Copy the id_rsa.pub from the /.ssh directory on your local machine to the /home/remoteserver//.ssh directory on the remoteserver server: - -``` -scp id_rsa.pub @yourserver.com:/home/remoteserver//.ssh -``` - -Switch back into your terminal window that is connected to remoteserver.com, change directory to the .ssh directory, and rename the file from id_rsa.pub to `authorized_keys` (without any file extension): - -``` -mv id_rsa.pub authorized_keys -``` - -Change the file permissions to 700: - -``` -chmod 700 authorized_keys -``` - -Now you should be able to SSH onto remoteserver without any password prompts. - -Open another terminal (which is not already SSH'd into remoteserver.com) and try the following: - -``` -ssh @remoteserver.com -``` - -If successful, you shouldn't be prompted for a password. - -Now that you can connect without password prompts, you can use the scp scripts to transfer files to the server without password prompts. For example: - -``` -scp -r ../doc_outputs/mydoc/writers @remoteserver:/var/www/html/ -``` \ No newline at end of file +11. Open another terminal (which is not already SSH'd into remoteserver.com) and try the following: + + ``` + ssh @remoteserver.com + ``` + + If successful, you shouldn't be prompted for a password. + + Now that you can connect without password prompts, you can use the scp scripts to transfer files to the server without password prompts. For example: + + ``` + scp -r ../doc_outputs/mydoc/writers @remoteserver:/var/www/html/ + ``` \ No newline at end of file diff --git a/mydoc/mydoc_push_build_to_server.md b/mydoc/mydoc_push_build_to_server.md index eb7bacd..56375c7 100644 --- a/mydoc/mydoc_push_build_to_server.md +++ b/mydoc/mydoc_push_build_to_server.md @@ -14,19 +14,19 @@ permalink: /mydoc_push_build_to_server/ If you have the AWS Command Line Interface installed and are pushing your builds to AWS, the following commands show how you can build and push to an AWS location from the command line: ``` -#aws s3 cp ~/users/tjohnson/projects/documentation-theme-jekyll-builds/mydoc_writers s3://[aws path]documentation-theme-jekyll/mydoc_writers --recursive +aws s3 cp ~/users/tjohnson/projects/mydocproject/ s3://[aws path]docpath/mydocproject --recursive -#aws s3 cp ~/users/tjohnson/projects/documentation-theme-jekyll-builds/mydoc_designers s3://[aws path]/documentation-theme-jekyll/mydoc_designers --recursive +aws s3 cp ~/users/tjohnson/projects/anotherdocproject2/ s3://[aws path]docpath/anotherdocproject --recursive ``` -The first path is the local location; the second path is the destination. +The first path in the argument is the local location; the second path is the destination. ## Pushing to a regular server If you're pushing to a regular server that you can ssh into, you can use `scp` commands to push your build. Here's an example: ``` -scp -r /users/tjohnson/projects/documentation-theme-jekyll-builds/mydoc_writers name@domain:/var/www/html/documentation-theme-jekyll/mydoc_writers +scp -r /users/tjohnson/projects/mydocproject/ name@domain:/var/www/html/mydocproject ``` Similar to the above, the first path is the local location; the second path is the destination. diff --git a/mydoc/mydoc_release_notes_50.md b/mydoc/mydoc_release_notes_50.md new file mode 100644 index 0000000..f843ca9 --- /dev/null +++ b/mydoc/mydoc_release_notes_50.md @@ -0,0 +1,27 @@ +--- +title: Release notes 5.0 +tags: [getting_started] +keywords: release notes, announcements, what's new, new features +last_updated: March 20, 2016 +summary: "Version 5.0 of the Documentation theme for Jekyll changes some fundamental ways the theme works to provide product-specific sidebars, intended to accommodate a site where multiple products are grouped together on the same site rather than generated out as separate outputs." +sidebar: mydoc_sidebar +permalink: /mydoc_release_notes_50/ +--- + +## Unique sidebars for each product + +In previous versions of the theme, I architected the theme to generate different outputs for different scenarios based on various filtering attributes including product, version, platform, and audience. + +However, this model results in siloed outputs and lots of different file directories to manage. Instead of having 10 separate sites for your content, in this version of the theme I move towards a strategy of having one site with multiple products. + +For each product, you can associate a unique sidebar with each of the product's pages. This allows you to easily browse products and have a unique sidebar appear for each product. + +You can still output to both web and PDF. + +## Permalinks + +Since you'll be publishing to one site, I've implement permalinks instead of using relative links. Using permalinks means the way you store pages is much more flexible. You can use folders and subfolders etc. to any degree. But if you want to view the content offline or on a separate site other than the one specified in the configuration file, you won't be able to do that. + +## Updated documentation + +I updated the documentation for using the theme. The switch from the multi-site outputs to the single-site with multiple sidebars required updating a lot of different parts of the documentation and code. \ No newline at end of file diff --git a/mydoc/mydoc_search_configuration.md b/mydoc/mydoc_search_configuration.md index c2c3edd..adfe42c 100644 --- a/mydoc/mydoc_search_configuration.md +++ b/mydoc/mydoc_search_configuration.md @@ -8,11 +8,8 @@ sidebar: mydoc_sidebar permalink: /mydoc_search_configuration/ --- - ## About search -The search is configured through the search.json file in the root directory. Take a look at that code if you want to change what fields are included. - -The search is a simple search that looks at content in pages. It looks at titles, summaries, keywords, and tags. +The search is configured through the search.json file in the root directory. The search is a simple search that looks at content in pages. It looks at titles, summaries, keywords, and tags. However, the search doesn't work like google — you can't hit return and see a list of results on the search results page, with the keywords in bold. Instead, this search shows a list of page titles that contain keyword matches. It's fast, but simple. @@ -20,17 +17,20 @@ However, the search doesn't work like google — you can't hit return and se By default, every page is included in the search. Depending on the type of content you're including, you may find that some pages will break the JSON formatting. If that happens, then the search will no longer work. -If you want to exclude a page from search add `search: exclude` in the frontmatter. +If you want to exclude a page from search add `search: exclude` in the page's frontmatter. ## Troubleshooting search -You should exclude any files from search that you don't want appearing in the search results. For example, if you have a tooltips.json file or prince-file-list.txt, don't include it, as the formatting will break the JSON format. +You should exclude any files from search that you don't want appearing in the search results. For example, if you have a tooltips.json file or prince-list.txt, don't include it, as the formatting will break the JSON format. If any formatting in the search.json file is invalid (in the build), search won't work. You'll know that search isn't working if no results appear when you start typing in the search box. -If this happens, go directly to the search.json file in your browser, and then copy the content. Go to a [JSON validator](http://jsonlint.com/) and paste in the content. Look for the line causing trouble. Edit the file to either exclude it from search or fix the syntax so that it doesn't invalidate the JSON. +If this happens, go directly to the search.json file in your browser, and then copy the content. Go to a [JSON validator](http://jsonlint.com/) and paste in the content. Look for the line causing trouble. Edit the file to either exclude the page from search or fix the syntax so that it doesn't invalidate the JSON. (Note that tabs in the body will invalidate JSON.) -The search.json file already tries to strip out content that would otherwise make the JSON invalid: +The search.json file already tries to strip out content that would otherwise make the JSON invalid. + +## Including the body field in search +I've found that include the `body` field in the search creates too many problems, and so I've removed `body` from the search. You can see the results of including the `body` by adding this along with the other fields in search.json: {% raw %} ```json @@ -38,55 +38,78 @@ The search.json file already tries to strip out content that would otherwise mak ``` {% endraw %} -Note that the last replace, `| replace: '^t', ' ' `, looks for any tab character and replaces it with four spaces. Yes, an innocent little tab character invalidates JSON. Geez. If you run into other problematic formatting, you can use regex expressions to find and replace the content. See [Regular Expressions](http://www.ultraedit.com/support/tutorials_power_tips/ultraedit/regular_expressions.html) for details on finding and replacing code. +Note that the last replace, `| replace: '^t', ' ' `, looks for any tab character and replaces it with four spaces. (Tab characters invalidate JSON.) If you run into other problematic formatting, you can use regex expressions to find and replace the content. See [Regular Expressions](http://www.ultraedit.com/support/tutorials_power_tips/ultraedit/regular_expressions.html) for details on finding and replacing code. It's possible that the formatting may not account for all the scenarios that would invalidate the JSON. (Sometimes it's an extra comma after the last item that makes it invalid.) -{% if site.audience == "designers" %} +Note that including the body in the search creates other problems as well. The search results show the most immediate matches in the JSON file. If several topics have matches for the keyword in the body, these matches might appear before other files that have matches in the title, summary, or keywords. This is because this simple search does not provide any weighting mechanisms for the content. + ## Customizing search results At some point, you may want to customize the search results more. Here's a little more detail that will be helpful. The search.json file retrieves various page values: ```json -{% raw %} - {% if page.search == true %} - { - "title": "{{ page.title | escape }}", - "tags": "{{ page.tags }}", - "keywords": "{{page.keywords}}", - "url": "{{ page.url | replace: "/", "" }}", - "last_updated": "{{ page.last_updated }}", - "summary": "{{page.summary}}", - "body": "{{ page.content | strip_html | strip_newlines | replace: '\', '\\\\' | replace: '"', '\\"' }}" - } -{% endraw %} +{% raw %}--- +title: search +layout: none +search: exclude +--- + +[ +{% for page in site.pages %} +{% unless page.search == "exclude" %} +{ +"title": "{{ page.title | escape }}", +"tags": "{{ page.tags }}", +"keywords": "{{page.keywords}}", +"url": "{{ page.url | prepend: site.baseurl }}", +"summary": "{{page.summary | strip }}" +}, +{% endunless %} +{% endfor %} + +{% for post in site.posts %} + +{ +"title": "{{ post.title | escape }}", +"tags": "{{ post.tags }}", +"keywords": "{{post.keywords}}", +"url": "{{ post.url | prepend: site.baseurl }}", +"summary": "{{post.summary | strip }}" +} +{% unless forloop.last %},{% endunless %} +{% endfor %} + +]{% endraw %} ``` The \_includes/topnav.html file then makes use of these values: ```html - -
    - -
      -
      - - - +
    • + +
      + +
        +
        + + +
        • ``` Where you see `{url}` and `{title}`, the search is retrieving the values for these as specified in the search.json file. -At some point, you may want to add in the `{summary}` as well. You could create a dedicated search page that could include the summary as an instant result as you type. -{% endif %} \ No newline at end of file +## More robust search + +For more robust search, consider integrating either [Algolia](http://algolia.com) or [Swifttype](http://swiftype.com). \ No newline at end of file diff --git a/mydoc/mydoc_support.md b/mydoc/mydoc_support.md index f5a4211..7945842 100644 --- a/mydoc/mydoc_support.md +++ b/mydoc/mydoc_support.md @@ -1,6 +1,6 @@ --- title: Support -tags: [getting_started] +tags: [getting_started, troubleshooting] keywords: questions, troubleshooting, contact, support last_updated: March 20, 2016 summary: "Contact me for any support issues." diff --git a/mydoc/mydoc_troubleshooting.md b/mydoc/mydoc_troubleshooting.md index 0a783ef..f7da4a2 100644 --- a/mydoc/mydoc_troubleshooting.md +++ b/mydoc/mydoc_troubleshooting.md @@ -1,6 +1,6 @@ --- title: Troubleshooting -tags: [getting_started] +tags: [troubleshooting] keywords: trouble, problems, support, error messages, problems, failure, error, #fail last_updated: March 20, 2016 summary: "This page lists common errors and the steps needed to troubleshoot them." @@ -8,7 +8,6 @@ sidebar: mydoc_sidebar permalink: /mydoc_troubleshooting/ --- - ## Issues building the site ### Address already in use @@ -34,20 +33,6 @@ Alternatively, type the following to stop all Jekyll servers: kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}') ``` -### Build not entirely finishing - -If your build doesn't entirely finish on the command line, check to see if you have a space after a comma when using multiple configuration files, like this: - -``` -jekyll serve --config config_base.yml, config_designer.yml -``` - -Remove the space after the comma, and the build will finish executing: - -``` -jekyll serve --config config_base.yml,config_designer.yml -``` - ### shell file not executable If you run into permissions errors trying to run a shell script file (such as mydoc_multibuild_web.sh), you may need to change the file permissions to make the sh file executable. Browse to the directory containing the shell script and run the following: @@ -56,37 +41,29 @@ If you run into permissions errors trying to run a shell script file (such as my chmod +x build_writer.sh ``` -### Pygments not installed +## shell file not runnable -The config file requires pygments for the highlighter. You must [download and install Pygments](http://pygments.org/download/), which requires Python, in order to use this syntax highlighter. If you don't want to bother with Pygments, open the configuration file and change `pygments` to `rouge`. +If you're using a PC, rename your shell files with a .bat extension. ### "page 0" cross references in the PDF - If you see "page 0" cross-references in the PDF, the URL doesn't exist. Check to make sure you actually included this page in the build. - - If it's not a page but rather a file, you need to add a `noCrossRef` class to the file so that your print stylesheet excludes the counter from it. Add `class="noCrossRef"` as an attribute to the link. In the css/printstyles.css file, there is a style that should remove the counter from anchor elements with this class. +If you see "page 0" cross-references in the PDF, the URL doesn't exist. Check to make sure you actually included this page in the build. + +If it's not a page but rather a file, you need to add a `noCrossRef` class to the file so that your print stylesheet excludes the counter from it. Add `class="noCrossRef"` as an attribute to the link. In the css/printstyles.css file, there is a style that should remove the counter from anchor elements with this class. ### The PDF is blank - Check the prince-file-list.txt file in the output to see if it contains links. If not, you have something wrong with the logic in the prince-file-list.txt file. Check the conditions.html file in your \_includes to see if the audience specified in your configuration file aligns with the buildAudience in the conditions.html file +Check the prince-list.txt file in the output to see if it contains links. If not, you have something wrong with the logic in the prince-list.txt file. Check the conditions.html file in your \_includes to see if the audience specified in your configuration file aligns with the buildAudience in the conditions.html file ### Sidebar not appearing - If you build your site but the sidebar doesn't appear, check the following: +If you build your site but the sidebar doesn't appear, check the following: - Look in \_includes/custom/sidebarconfigs.html and make sure the conditional values there match up with the values declared in the configuration file. Specifically, you need to make sure you've declared a value for project, product, platform, and version. +Look in \_includes/custom/sidebarconfigs.html and make sure the conditional values there match up with values you're using in each page's frontmatter. - If you don't have any values for these properties, you still need to keep them in your configuration file. Just put something like `all` as the value. +Make sure each TOC item has an output property that specifies web or pdf. - {{site.data.alerts.note}} This theme is designed for single sourcing. If you're only building one site, you can remove these values from the \_includes/sidebar.html file and \_data/sidebar.yml files.{{site.data.alerts.end}} - - Understanding how the theme works can be helpful in troubleshooting. The \_includes/sidebar.html file loops through the values in the \_data/sidebar.yml file. There are `if` statements that check whether the conditions (as specified in the conditions.html file) are met. If the sidebar.yml item has the right product, platform, audience, and version, then it gets displayed in the sidebar. If not, it get skipped. - -### Sidebar heading level not opening - - In your \_data/sidebar.yml file, you must also include the correct parameters (platform, product, audience version) for each heading. If an item contains something that should be displayed, the attributes for the heading should be listed. - - Without any attributes on heading levels, you could end up with scenarios where a section is entirely designed for one output but appears in every output regardless. +Understanding how the theme works can be helpful in troubleshooting. The \_includes/sidebar.html file loops through the values in the \_data/sidebar.yml file. There are `if` statements that check whether the conditions (as specified in the conditions.html file) are met. If the sidebar.yml item doesn't have the right output, then it won't get displayed in the sidebar. It would instead get skipped. ### Sidebar isn't collapsed diff --git a/mydoc/mydoc_webstorm_text_editor.md b/mydoc/mydoc_webstorm_text_editor.md index c4b0c28..1b194b9 100644 --- a/mydoc/mydoc_webstorm_text_editor.md +++ b/mydoc/mydoc_webstorm_text_editor.md @@ -28,6 +28,14 @@ Most likely you'll want to enable soft wraps, which wraps lines rather than exte When you're searching for content, you don't want to edit any file that appears in the \_site directory. You can exclude a directory from Webstorm by right-clicking the directory and choosing **Mark Directory As** and then selecting **Excluded**. +## Set tabs to 3 spaces + +You can set the default number of spaces a tab sets, including whether Webstorm uses a tab character or spaces. You want spaces, and you want to set this to default number of spaces to ```3``` spaces instead of 4. Note that this is due to the way Kramdown handles the continuation of lists. + +When you intercept a list with a paragraph or code sample, the indentation of the intercepting paragraph or list must align with the beginning of the first character after the space in the list item numbering. This is typically 3 spaces, not 4. Note that this style differs from the Github-flavored Markdown style. (Welcome to the world of subtle and infuriating discrepancies between Markdown flavors.) + +To set the indentation, see the "Tabs and Indents" topic in this [Code Style. Javascript](https://www.jetbrains.com/help/webstorm/2016.1/code-style-javascript.html?origin=old_help#d658997e132) topic in Webstorm's help. + ## Shortcuts It can help to learn a few key shortcuts: diff --git a/search.json b/search.json index f34549a..890b19f 100644 --- a/search.json +++ b/search.json @@ -12,7 +12,7 @@ search: exclude "tags": "{{ page.tags }}", "keywords": "{{page.keywords}}", "url": "{{ page.url | prepend: site.baseurl }}", -"summary": "{{page.summary}}" +"summary": "{{page.summary | strip }}" }, {% endunless %} {% endfor %} @@ -24,7 +24,7 @@ search: exclude "tags": "{{ post.tags }}", "keywords": "{{post.keywords}}", "url": "{{ post.url | prepend: site.baseurl }}", -"summary": "{{post.summary}}" +"summary": "{{post.summary | strip }}" } {% unless forloop.last %},{% endunless %} {% endfor %} diff --git a/tags/tag_single_sourcing.html b/tags/tag_single_sourcing.html index d54d04e..9a7b92c 100644 --- a/tags/tag_single_sourcing.html +++ b/tags/tag_single_sourcing.html @@ -1,5 +1,5 @@ --- -title: "single_sourcing pages" +title: "Single sourcing pages" tagName: single_sourcing search: exclude permalink: /tag_single_sourcing/ diff --git a/tags/tag_troubleshooting.html b/tags/tag_troubleshooting.html new file mode 100644 index 0000000..fcdce6c --- /dev/null +++ b/tags/tag_troubleshooting.html @@ -0,0 +1,8 @@ +--- +title: "Troubleshooting pages" +tagName: troubleshooting +search: exclude +permalink: /tag_troubleshooting/ +sidebar: tags_sidebar +--- +{% include taglogic.html %} \ No newline at end of file diff --git a/tooltips.html b/tooltips.html index 133ffc2..2a4b931 100644 --- a/tooltips.html +++ b/tooltips.html @@ -1,5 +1,6 @@ --- layout: none +search: exclude ---