[
https://issues.apache.org/jira/browse/SOLR-14173?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17053789#comment-17053789
]
Cassandra Targett commented on SOLR-14173:
------------------------------------------
I've worked on this on & off for the past couple of months and have it pretty
close to done. From my list of Known Issues before:
* -The fancy tab thing for multiple code examples in one section isn't styled
right when you click other tabs- Fixed now.
* -The top nav won't be responsive in smaller screens- Finally figured out how
to do this responsively
* -Behavior of sidebar on smaller screens could be improved- This is better now
* -Still many overlapping CSS rules for elements and many unused CSS rules to
be cleaned up- Did a lot of cleanup here
* Sidebar requires too much scrolling - Phase 2 will trim this down
* -Now unused CSS/JS files haven't been deleted yet-
* -Search box shows results in the sidebar nav - I wasn't able to see this
until yesterday and not sure how I feel about it. At any rate, I haven't worked
with it much yet and it needs more work- I worked on this extensively and think
it's OK now
* -Home page (index.html) needs some additional love- I don't remember what I
meant by this, but I worked on that too and it's fine now.
Besides fixing these things, I also changed the left nav a little bit in terms
of colors of child pages, etc. I don't want to spend too much time on that
since Phase 2 will be a re-org that will require some additional work in this
area.
I've updated the demo site at
https://people.apache.org/~ctargett/RefGuideRedesign/ as I've gone along, it's
up to date with my latest changes today. I have not pushed the branch in a
while, I think I will actually make a new branch since this one is really far
behind and trying to update it gives me weird merge conflicts I really don't
want to deal with.
Comments? Feedback?
> 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
>
> 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
