Move documentation to docs folder #5459

Merged
merged 8 commits into from Nov 2, 2016

Projects

None yet

8 participants

@benbalter
Contributor

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
Member
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 👍.

@parkr

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

rake/site.rake
-
- File.open('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
parkr Oct 6, 2016 Member

Or get rid of this.

rake/site.rake
- 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"
end
puts 'Done.'
end
@parkr
parkr Oct 6, 2016 Member

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

docs/_data/docs.yml
@@ -46,5 +46,6 @@
- title: Meta
docs:
- contributing
+ - development
@parkr
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 jekyllrb.com website?

@ashmaroli
Contributor

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..
Thanks

@parkr parkr added the documentation label Oct 11, 2016
@DirtyF DirtyF was assigned by jekyllbot Oct 11, 2016
@zdroid
Member
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
Member
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
Member
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
Member
parkr commented Oct 19, 2016

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

@parkr
Member
parkr commented Nov 2, 2016

GitHub Pages is now running Jekyll 3.3. 🎉 https://github.com/blog/2277-what-s-new-in-github-pages-with-jekyll-3-3

@parkr
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.
db4c571
@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. 💫
1669f94
@@ -14,6 +13,9 @@ timezone: America/Los_Angeles
collections:
docs:
output: true
+ posts:
+ permalink: /news/:year/:month/:day/:title/
+ output: true
name: Jekyll • Simple, blog-aware, static sites
@zdroid
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
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
XhmikosR Nov 2, 2016 Contributor

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

@zdroid
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
Member
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
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@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