Migrate reference docs

[nex3]

The Sass reference has never been the most user-friendly documentation, and as Ruby Sass moves towards end-of-life it'll be more important not to pull the primary source of language documentation from its repository and infrastructure. I think the best thing to do would be to make the reference documentation a native part of the site, and take that opportunity to rethink how it's presented. This includes function documentation, which is currently even more tightly coupled to Ruby.

@sass/core @sass/sass-site I'm happy to take on the work of and updating the prose, but I could use some help figuring out the best way to present it. I'm thinking roughly taking each sub-section of the existing reference and making it a separate page, with some sort of table of contents making it easier to navigate. Python's language documentation is good prior art here, but I'd very much appreciate suggestions from folks who regularly consume this sort of documentation.

I'll also need some design assistance getting the reference layout looking nice and consistent with the rest of the site.

[nex3]

We should also be careful to ensure that widely-used existing URLs continue to work. In particular:

• /documentation/file.SASS_REFERENCE.html should 301 redirect to the root of the new documentation. That documentation should have a bit of JavaScript that looks for a URL fragment and, if one is found that matches a fragment in the old reference, does a client-side redirect to a more specific location.

• /documentation/Sass/Script/Functions.html should 301 redirect to the new function documentation, doing a similar fragment trick as above to go to a specific page if possible.

• /documentation/file.SASS_CHANGELOG.html should 301 redirect to a language changelog (which should probably be pulled from sass/language as per Update repository structure for a post-Ruby-Sass world sass#2480).

• /documentation/file.INDENTED_SYNTAX.html and /documentation/file.SCSS_FOR_SASS_USERS.html should both 301 redirect to a new page that explains the difference between the indented and SCSS syntaxes.

• All other /documentation/* URLs should redirect to http://www.rubydoc.info/gems/sass/*.

[nex3]

@jina I think there's enough material now on the wip.reference branch for you to take a look at fixing up the design. A few things to note:

• I'm envisioning the table of contents (which is currently a static part of the layout) as a kind of visually-delineated sidebar thing on the left.
• The page title takes up a lot of vertical space... it might be a good idea to make it less obtrusive.
• I've added HTML for a compatibility table that I intend to re-use (it's currently only used in the documentation/syntax/parsing). That needs some sort of nice neat styling, probably with color-coding for supported versus unsupported.
• I've also added HTML for an implementation-note aside, which probably wants some sort of relatively subtle styling.

I leave the details and the final decision-making in your capable hands, though!

[tomByrer]

I'm OK with current 1-page layout, though I wish the menu floated.

But the references to Ruby-sass, eg configuration files are very confusing & I hope are changed soon.

[jina]

we have an open ticket being looked at for doing a sticky nav: #268