New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrate reference docs #205

Open
nex3 opened this Issue Mar 11, 2018 · 2 comments

Comments

1 participant
@nex3
Contributor

nex3 commented Mar 11, 2018

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

This comment has been minimized.

Contributor

nex3 commented Mar 13, 2018

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 sass/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

This comment has been minimized.

Contributor

nex3 commented Aug 16, 2018

@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!

nex3 added a commit that referenced this issue Aug 29, 2018

nex3 added a commit that referenced this issue Aug 30, 2018

@nex3 nex3 added this to In progress in Onsite Sass Reference Sep 27, 2018

jina added a commit that referenced this issue Oct 22, 2018

Add a helper for writing inline multi-syntax examples (#226)
* Add a helper for writing inline multi-syntax examples

This will be useful for #205.

* Add the ability to add CSS output to the syntax switcher

* Automatically generate CSS for the syntax switcher by default

* Fix most lints

* Fix a specificity bug

* Show SCSS syntax by default

* Fix a couple more lints

* Make the example helper template-engine-agnostic

* Support a "syntax switcher" with a single syntax

This will make it possible to do nice-looking single-syntax code
examples in the reference.

* Remove trailing whitespace
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment