Move documentation to docs folder #5459

merged 8 commits into from Nov 2, 2016


None yet

8 participants


Per #5409, this pull requests moves the user-facing documentation from the site folder to the docs folder where we can rely on Pages to automatically generate the docs for us.

To do this, I did a few things:

  1. Abstract the docs folder to a variable in the rake task
  2. Move the rake task to use the docs folder rather than the site folder
  3. Moved the actual folder content
  4. Migrated the maintainer docs, which was at /docs to /docs/_docs/development/, and added YAML front matter.

There should be no other change to the user-facing site content.

Also to note, rake site:publish simply runs rake site:generated_pages and commits and pushes the result (since we no longer need to do the multiple branch dance). It may be possible to have Jekyllbot do this after each release (to update the history and contributing files).

Once this merges, we can delete the gh-pages branch. We're also working to get this repo early access to new releases of Jekyll, so that it can always be running the latest stable version, regardless of what version other Pages users are using.

Fixes #5409.

zdroid commented Oct 6, 2016

We're also working to get this repo early access to new releases of Jekyll, so that it can always be running the latest stable version, regardless of what version other Pages users are using.

Exactly why this change is awesome. Big 👍.


Nice! You can also remove docs/.gitignore. 😄

-'gh-pages/.nojekyll', 'wb') { |f| f.puts(":dog: food.") }
- # Commit and push.
puts "Committing and pushing to GitHub Pages..."
sha = `git rev-parse HEAD`.strip
Dir.chdir('gh-pages') do
parkr Oct 6, 2016 Member

Or get rid of this.

- sh "git push origin gh-pages"
+ sh "git add docs/"
+ sh "git commit --allow-empty -m 'Generating pages for #{sha}.'"
+ sh "git push origin master"
puts 'Done.'
parkr Oct 6, 2016 Member

This can be removed. I'll just change the settings so it uses master /docs.

@@ -46,5 +46,6 @@
- title: Meta
- contributing
+ - development
parkr Oct 6, 2016 Member

I think I'd like this to be called maintaining or something like that. @jekyll/affinity-team-captains, how do you feel about putting your docs on the website?


I have a personal request:
Can we consider renaming all existing .markdown posts to .md before implementing this PR?
I've a PR at #5176 dealing with this..

@parkr parkr added the documentation label Oct 11, 2016
@DirtyF DirtyF was assigned by jekyllbot Oct 11, 2016
zdroid commented Oct 19, 2016 edited

@benbalter Any progress on this? The number of conflicted files is increasing, so it'll be easier to finish and merge it sooner than later.

DirtyF commented Oct 19, 2016

@zdroid Subscribe to the issue if you want to follow progress, but please don't put pressure on maintainers, we're all volunteers, there is no rush for this.

zdroid commented Oct 19, 2016

@DirtyF I did subscribe, don't worry. I'm sorry if I rushed anyone, I know it's hard to keep up with working on open source project. 😄

parkr commented Oct 19, 2016

@zdroid Thanks for the nudge! This is actually waiting on availability of Jekyll 3.3 on GitHub Pages.

parkr commented Nov 2, 2016

GitHub Pages is now running Jekyll 3.3. 🎉

parkr approved these changes Nov 2, 2016 View changes
benbalter and others added some commits Oct 6, 2016
@benbalter @parkr benbalter abstract site directory to variable 3eedfd8
@benbalter @parkr benbalter abstract one last site reference 8b9391d
@benbalter @parkr benbalter update rake task to use docs folder a087d34
@benbalter @parkr benbalter move site to docs folder 6be62de
@sverrirs @parkr sverrirs Updating install instruction link
Adding a link to updated installation instructions for Jekyll 3 and Ruby 2.2.5. These instructions were adapted and significantly updated from the earlier work of Julian Thilo which is now outdated.
@parkr parkr Move docs/development to docs/maintaining b108f4c
@parkr parkr Instead of a sleep hack, just use a Jekyll hook! 😄 8b2a35d
@parkr parkr Move posts-specific permalink into collections metadata. Way better. 💫
@@ -14,6 +13,9 @@ timezone: America/Los_Angeles
output: true
+ posts:
+ permalink: /news/:year/:month/:day/:title/
+ output: true
name: Jekyll • Simple, blog-aware, static sites
zdroid Nov 2, 2016 edited Member

Shouldn't be escaped as ·? I've just noticed this, I know it's not related to the actual commit.

parkr Nov 2, 2016 Member

Do you know if it's causing an issue at all? I kind of like the UTF-8 dot. 😄

XhmikosR Nov 2, 2016 Contributor

It should be OK since the HTML files are using utf-8.

zdroid Nov 2, 2016 Member

Actually, it's fine. The old browsers such as IE6/7 (I am unsure for others) had character-encoding problems, but nobody uses them anymore. Keep the cool character as is.

parkr commented Nov 2, 2016

@jekyllbot: merge +site

@jekyllbot jekyllbot merged commit 2115b73 into master Nov 2, 2016

1 of 2 checks passed

continuous-integration/appveyor/pr Waiting for AppVeyor build to complete
continuous-integration/travis-ci/pr The Travis CI build passed
@jekyllbot jekyllbot deleted the docs-folder branch Nov 2, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment