[
https://issues.apache.org/jira/browse/SOLR-14173?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17009848#comment-17009848
]
Cassandra Targett commented on SOLR-14173:
------------------------------------------
The branch with my work so far is in a branch ({{jira/solr-14173}}). Github
link: https://github.com/apache/lucene-solr/tree/jira/solr-14173.
It's still a WIP so I won't create a PR for it yet unless someone wants one. I
did however, put up files at:
http://home.apache.org/~ctargett/RefGuideRedesign/index.html. Feel free to take
a look and let me know your thoughts on overall look & feel and if you find
buggy behavior.
*There are still bugs* - I'll list them below.
h3. What's Changed
*Updated dependencies*
Updated:
* Bootstrap 3.3.7 to 4.1.3
* JQuery 2.1.4 to 3.3.1
* AnchorJS 2.0.0 to 4.2.0
Added:
* Malihu Custom Scrollbar 3.1.5 - to make the new sidebar scroll
* PopperJS 1.14.3 - required by Bootstrap
Removed:
* {{toc.js}} - no longer needed
*New Layout*
* Sidebar nav is now fixed to the left side of the screen and content is to the
right designed to use as much space to the right as the browser has available
(up to 1238px or so, I think)
* Top nav does not span the page, but stays on top of the content to give room
for the sidebar nav
* Changed the in-page TOCs to be built at the time the HTML is generated. This
makes all in-page TOCs now always float to the right side of the page (IOW, we
lost ability to choose where to put it but IMO this is a simplification)
*CSS Cleanup*
* Removed lavish-bootstrap.css and replaced with Bootstrap's native CSS (which
will be easier to upgrade in the future)
* Re-organized all the CSS files and separated them into broad groups:
** decoration.css: buttons, forms, horizontal lines, lead paragraphs, tabs/pills
** navs.css: all navigation elements such as the top nav, sidebar nav, footer,
in-page TOC
** ref-guide.css: all elements which impact the display of content such as
overall body, tables, lists, links, code samples, etc.
** search.css: all elements related to the page-title lookup
* Moved CSS elements from other files into the above files and organized them
by what they control
* Added significant comments to CSS files about what rules are controlling and
how those elements are used (more to do here)
h3. Known Issues
* The fancy tab thing for multiple code examples in one section isn't styled
right when you click other tabs
* The top nav won't be responsive in smaller screens
* Behavior of sidebar on smaller screens could be improved
* Still many overlapping CSS rules for elements and many unused CSS rules to be
cleaned up
* 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
> Ref Guide Redesign
> ------------------
>
> Key: SOLR-14173
> URL: https://issues.apache.org/jira/browse/SOLR-14173
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> 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
