[
https://issues.apache.org/jira/browse/SOLR-14173?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17057332#comment-17057332
]
Cassandra Targett commented on SOLR-14173:
------------------------------------------
I've sat with the gray theme for a couple of days and prefer it, so I committed
those changes and updated my demo site:
http://people.apache.org/~ctargett/RefGuideRedesign/index.html.
I added in some CSS changes to make the current page being viewed more obvious
(it will be bold).
There's only one more issue that I can tell, which is to get the sidebar to
scroll to the section of the nav that shows the current page. But the same
problem exists today (not sure why I never noticed it) and my goal with phase 2
is to make a number of improvements to page organization and simplify that nav
a lot more, so I'm willing to go ahead with it as is and hopefully address it
in the future.
I think this is otherwise ready to go into master and branch_8x. I hadn't
planned on doing it on branch_8_5, but since that hasn't been published yet, I
could (timing seems to work out).
I could also backport it into branch_8_4 and all previous ref guide branches
(back to branch_6_6) so they are all consistent in look & feel...not sure if
anyone has an opinion about that.
> Ref Guide Redesign
> ------------------
>
> Key: SOLR-14173
> URL: https://issues.apache.org/jira/browse/SOLR-14173
> Project: Solr
> Issue Type: Improvement
> Components: documentation
> Reporter: Cassandra Targett
> Assignee: Cassandra Targett
> Priority: Major
> Attachments: SOLR-14173.patch, blue-left-nav.png, gray-left-nav.png
>
>
> The current design of the Ref Guide was essentially copied from a
> Jekyll-based documentation theme
> (https://idratherbewriting.com/documentation-theme-jekyll/), which had a
> couple important benefits for that time:
> * It was well-documented and since I had little experience with Jekyll and
> its Liquid templates and since I was the one doing it, I wanted to make it as
> easy on myself as possible
> * It was designed for documentation specifically so took care of all the
> things like inter-page navigation, etc.
> * It helped us get from Confluence to our current system quickly
> It had some drawbacks, though:
> * It wasted a lot of space on the page
> * The theme was built for Markdown files, so did not take advantage of the
> features of the {{jekyll-asciidoc}} plugin we use (the in-page TOC being one
> big example - the plugin could create it at build time, but the theme
> included JS to do it as the page loads, so we use the JS)
> * It had a lot of JS and overlapping CSS files. While it used Bootstrap it
> used a customized CSS on top of it for theming that made modifications
> complex (it was hard to figure out how exactly a change would behave)
> * With all the stuff I'd changed in my bumbling way just to get things to
> work back then, I broke a lot of the stuff Bootstrap is supposed to give us
> in terms of responsiveness and making the Guide usable even on smaller screen
> sizes.
> After upgrading the Asciidoctor components in SOLR-12786 and stopping the PDF
> (SOLR-13782), I wanted to try to set us up for a more flexible system. We
> need it for things like Joel's work on the visual guide for streaming
> expressions (SOLR-13105), and in order to implement other ideas we might have
> on how to present information in the future.
> I view this issue as a phase 1 of an overall redesign that I've already
> started in a local branch. I'll explain in a comment the changes I've already
> made, and will use this issue to create and push a branch where we can
> discuss in more detail.
> Phase 1 here will be under-the-hood CSS/JS changes + overall page layout
> changes.
> Phase 2 (issue TBD) will be a wholesale re-organization of all the pages of
> the Guide.
> Phase 3 (issue TBD) will explore moving us from Jekyll to another static site
> generator that is better suited for our content format, file types, and build
> conventions.
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
