diff --git a/_config.yml b/_config.yml index 406f2da..cc34ebd 100644 --- a/_config.yml +++ b/_config.yml @@ -1,35 +1,50 @@ permalink: /:year/:month/:day/:title/ +# this sets the style for permalinks. The date formatting (/:year/:month/:day/) will only apply to blog posts, while the pages will just show the title. url: http://idratherbewriting.com +# where you plan to publish your site baseurl: "/documentation-theme-jekyll" +# any subdirectory that appears after the domain where you're publishing your site output: web +# this property is useful for conditional filtering of content that is separate from the PDF. topnav_title: Jekyll Documentation Theme +# this appears on the top navigation bar next to the home button site_title: Jekyll theme for designers +# this appears in the html browser tab for the site title (seen mostly by search engines, not users) company_name: Your company +# this appears in the footer github_editme_path: tomjohnson1492/documentation-theme-jekyll/edit/reviews +# if you're using Github, provide the basepath to the branch you've created for reviews, following the sample here. if not, leave this value blank. disqus_shortname: idrbwjekyll +# if you're using disqus for comments, add the shortname here. if not, leave this value blank. host: 127.0.0.1 +# the preview server used. Leave as is. port: 4009 +# the port where the preview is rendered. You can leave this as is unless you have other Jekyll builds using this same port that might cause conflicts. exclude: - _site - - _drafts - - configs/ + - _drafts/ + - .idea/ +# these are the files and directories that jekyll will exclude from the build feedback_email: tomjohnson1492@gmail.com - +# used as a contact email for the Feedback link in the top navigation bar highlighter: rouge +# library used for syntax highlighting + markdown: kramdown kramdown: input: GFM auto_ids: true hard_wrap: false syntax_highlighter: rouge - +# filter used to process markdown. note that kramdown differs from github-flavored markdown in some subtle ways collections: tooltips: output: false +# collection declared here. this renders the content in _tooltips and processes it, but doesn't output it as actual files in the output. defaults: - @@ -61,7 +76,8 @@ defaults: search: true sidebar: tags_sidebar +# these are defaults used for the frontmatter for these file types -# the description is used in the feed.xml file description: "Intended as a documentation theme based on Jekyll for technical writers documenting software and other technical products, this theme has all the elements you would need to handle multiple products with both multi-level sidebar navigation, tags, and other documentation features." +# the description is used in the feed.xml file \ No newline at end of file diff --git a/_data/sidebars/mydoc_sidebar.yml b/_data/sidebars/mydoc_sidebar.yml index 52251f8..5e83670 100644 --- a/_data/sidebars/mydoc_sidebar.yml +++ b/_data/sidebars/mydoc_sidebar.yml @@ -30,7 +30,7 @@ entries: - title: 5.0 Release notes url: /mydoc_release_notes_50/ output: web, pdf - + - title: Introduction url: /mydoc_introduction/ output: web, pdf @@ -187,6 +187,10 @@ entries: url: /mydoc_no_password_prompts_scp/ output: web, pdf + - title: Publishing on Github Pages + url: /mydoc_publishing_github_pages/ + output: web, pdf + - title: Special layouts output: web, pdf diff --git a/index.md b/index.md index b40a64e..53a9cbb 100644 --- a/index.md +++ b/index.md @@ -5,13 +5,18 @@ sidebar: mydoc_sidebar --- -## Getting up and running +## Make sure you can build a vanilla Jekyll site first 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). -After ensuring you can run Jekyll on your machine, you can build this site using the usual Jekyll command: `jekyll serve`. +## Build this theme + +1. Download the theme from the [Github repo for the Jekyll doc theme](https://github.com/tomjohnson1492/documentation-theme-jekyll). +2. Delete the Gemfile and Gemfile.lock files in the theme (unless you're planning to publish on Github Pages. If that's the case, see Publishing on Github Pages". +3. Customize the values in the \_config.yml file following the documentation included in that file). +3. Build the site using the usual Jekyll command: `jekyll serve`. ## Configuring the theme diff --git a/mydoc/mydoc_publishing_github_pages.md b/mydoc/mydoc_publishing_github_pages.md new file mode 100644 index 0000000..1e11b6a --- /dev/null +++ b/mydoc/mydoc_publishing_github_pages.md @@ -0,0 +1,82 @@ +--- +title: Publishing on Github Pages +sidebar: mydoc_sidebar +permalink: /mydoc_github_pages/ +summary: "You can publish your project on Github Pages, which is a free web hosting service provided by Github. All you need is to put your content into a Github repo branch called gh-pages and make this your default branch in your repo. With a Jekyll site, you just commit your entire project into the gh-pages branch and Github Pages will build the site for you." +--- + +## Set up your Github repo + +1. Make sure you have Git installed. You can download and install [Git for Windows here](https://git-scm.com/download/win) and [Git for Mac here](https://git-scm.com/download/mac). If you're on a Mac, chances are you might already have git installed. You can check by opening up a terminal and typing `which git`.{{end}} +1. Go to [Github.com](http://github.com) and sign up for an account. +2. Click the **+** button in the upper-right corner and select **New repository**. +3. Name the repository something like **mydoctheme**. +4. Type a description.. +5. Select the **Initialize this repository with a README** check box. +6. Add a license if desired. +7. Leave the other options at the defaults and click **Create repository**. +8. Click the **Settings** button. + + Github repo settings + +9. Go to your repository's home page, and click the branch drop-down menu. +10. Create a new branch called **gh-pages**. + + Creating a Github Pages branch + +11. Click **Settings** and change the default branch to **gh-pages**. + +11. Go back to your repository's homepage. With the gh-pages branch selected, copy the **https clone url**: + + clone URL + +12. Open a terminal, browse to a convenient location for your project, and type `git clone https://github.com/tomjohnson1492/myreponame.git`, replacing the `https://github.com/tomjohnson1492/myreponame.git` with your repository's https clone URL that you copied. +13. Move the jekyll theme files into this new folder that you just created in the previous step. +14. Open the _config.yml file and add the following: + + ``` + url: tomjohnson1492.github.io + baseurl: /myreponame + ``` + + Change the url to your github account name, and the baseurl to your repo name. + +## Install Bundler + +Bundler is a package manager for Ruby that will install all dependencies you might need to build your site locally. I recommend installing Bundler through homebrew. (Sorry, these instructions apply to Mac only.) + +1. Install [homebrew](http://brew.sh/): + + ``` + /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + ``` +2. Install Bundler: + + ``` + brew install bundler + ``` + + +## Add the github pages gem + +1. In terminal, browse to your Jekyll project directory. +2. Type `bundle init`. This creates a Gemfile and Gemfile.lock in your project. +3. Type `open gemfile`. This opens the gemfile in your default text editor. +4. Add the following in the gemfile (replacing the existing contents): + + ``` + source 'https://rubygems.org' + gem 'github-pages' + ``` + +5. Run `bundle install`. +14. Add the new jekyll files to git: `git add --all`. +15. Commit the files: `git commit -m "committing my jekyll theme"`. +16. Push the files up to your github repo: `git push`. + +Github Pages will now automatically build your site. Wait a minute or two, and then visit tomjohnson1492.github.io/yourreponame, replacing this path with your github account and branch. + +## Customize your URL + +You can also customize your Github URL. More instructions on this later.... +