Yeah...the one thing it does not have is an expanding-collapsing ToC. The scrolling is not bad, but the intimidation effect of endless topic titles can be large. For me that is a usability negative...but not a deal-killer.
On Sun, Jan 28, 2018 at 7:35 AM, Gabe Harbs <[email protected]> wrote: > BTW: > > That site has 3 levels in the table of contents: > https://redux.js.org/docs/recipes/reducers/PrerequisiteConcepts.html < > https://redux.js.org/docs/recipes/reducers/PrerequisiteConcepts.html> > > > On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala <[email protected]> > wrote: > > > > Here is a very good example of what the end product would look like: > > https://redux.js.org/ > > > > Thanks, > > Om > > > > On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala < > [email protected]> > > wrote: > > > >> > >> > >> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <[email protected]> > wrote: > >> > >>> Is this an additional way of viewing the content or a replacement for > the > >>> Jenkyll-produced site? > >>> > >>> If it’s the former, I can’t see any reason why not. > >>> > >> > >> It's an additional way. It uses the .md files from the github repo and > >> builds its own site. > >> > >> Thanks, > >> Om > >> > >> > >>> > >>> Harbs > >>> > >>>> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala < > [email protected]> > >>> wrote: > >>>> > >>>> I've been playing around with the tool: GitBook [www.gitbooks.io] > >>>> I was able to connect my personal fork of the royale-docs to my > >>> gitbooks.io > >>>> account. This way, all my .md files are automatically available for > >>> Docs > >>>> creation. > >>>> > >>>> Here is an example I created in a few minutes: > >>>> https://bigosmallm.gitbooks.io/royale-docs-test2/content/v/ > >>> develop/Create%20An%20Application.html > >>>> > >>>> The advantages I see using this tool are: > >>>> > >>>> * Seems to be a widely used tool for documentation these days. > >>> NPMjs.org, > >>>> React, Redux, etc. use Gitbook > >>>> * Two way sync between github and gitbook app. That is, you can > create > >>> an > >>>> .md file on github and see it on gitbook. You can also create more > >>> content > >>>> using the WYSIWYG editor on Gitbook, which will be synced to the > github > >>>> repo. > >>>> * Seems pretty straightforward to create a TOC. It includes support > for > >>>> tree structure by default > >>>> * We can choose to use the web app on gitbook.com or use the open > >>>> source(Apache V2 licensed | https://github.com/GitbookIO/gitbook) > >>> command > >>>> line tool. The CLI will help us integrate with our Jenkins build for > >>>> example. > >>>> * Allows users to provide feedback on the site itself > >>>> * Allows us to point the docs site to our custom domain address > >>>> > >>>> > >>>> If there is more interest in trying this out, I can set up an > >>> Organization > >>>> account (free) and add users as needed. > >>>> > >>>> Thanks, > >>>> Om > >>>> > >>>> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore <[email protected]> > >>> wrote: > >>>> > >>>>> If the ToC accordions properly and we need three levels, I do not see > >>> why > >>>>> three levels would cause more confusion than two levels. If this is a > >>>>> resource providing information people are going to need to use > Royale, > >>> and > >>>>> if that information is not readily available elsewhere, then we > should > >>> make > >>>>> the ToC fit the information, not the other way around. > >>>>> > >>>>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira < > >>> [email protected]> > >>>>> wrote: > >>>>> > >>>>>> Hi Alex, > >>>>>> > >>>>>> for TOC. One think that's very important to me: Please only *two > >>> levels* > >>>>> in > >>>>>> TOC. For simplicity and clarity. Like the demo page I did. It's the > >>>>>> standard right now and a three level only created confusion. Again > see > >>>>>> Angular and React sites to match what they did and take it as a > >>>>> reference. > >>>>>> > >>>>>> For states. I think the trick here is that a .md page has some > >>> variables > >>>>>> that will make the right top level branch open in TOC and as well > make > >>>>> the > >>>>>> right sub option appears as selected (strong type) and without link. > >>> As > >>>>> we > >>>>>> are dealing with static GitHub pages I think there's no concept of > >>>>>> component, only that all pages has the TOC added to the sidebar. > >>>>>> > >>>>>> > >>>>>> > >>>>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <[email protected]>: > >>>>>> > >>>>>>> What you describe sounds fine to me. I don't think we need to worry > >>>>> about > >>>>>>> breadcrumbs and state and helping people go backwards through their > >>>>>> series > >>>>>>> of clicks. > >>>>>>> > >>>>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui > <[email protected] > >>>> > >>>>>>> wrote: > >>>>>>> > >>>>>>>> Breaking out a separate thread on this... > >>>>>>>> > >>>>>>>> Thinking about this some more, I think I can generate an > interactive > >>>>>>>> control with Jekyll, but I don't know how to make it retain state. > >>> I > >>>>>>>> think that might require cookies and/or frames. > >>>>>>>> > >>>>>>>> For example, let's say the TOC looked like: > >>>>>>>> > >>>>>>>> Welcome > >>>>>>>> --High Level View > >>>>>>>> --Features > >>>>>>>> ----AS3 > >>>>>>>> ----MXML > >>>>>>>> Get Started > >>>>>>>> --Download > >>>>>>>> --Hello World > >>>>>>>> > >>>>>>>> I've already implemented logic in the template to auto-expand the > >>>>> tree > >>>>>> to > >>>>>>>> the document for folks who have direct links. So, if you do a > >>> Google > >>>>>>>> Search and find the link to the MXML page, when you go to that > page, > >>>>>> the > >>>>>>>> ToC will automatically look like: > >>>>>>>> > >>>>>>>> Welcome > >>>>>>>> --High Level View > >>>>>>>> --Features > >>>>>>>> ----AS3 > >>>>>>>> ---*MXML* > >>>>>>>> Get Started > >>>>>>>> > >>>>>>>> > >>>>>>>> > >>>>>>>> If you hit the main doc page, the ToC starts out collapsed so that > >>>>> Get > >>>>>>>> Started isn't pushed down by a bunch of Welcome sub-topics. So > the > >>>>> ToC > >>>>>>>> initially looks like: > >>>>>>>> > >>>>>>>> Welcome > >>>>>>>> Get Started > >>>>>>>> > >>>>>>>> Now let's say you expand both Welcome and Get Started so you see: > >>>>>>>> > >>>>>>>> Welcome > >>>>>>>> --High Level View > >>>>>>>> --Features > >>>>>>>> Get Started > >>>>>>>> --Download > >>>>>>>> --Hello World > >>>>>>>> > >>>>>>>> Then you click on Features. The logic that opens trees to direct > >>>>> links > >>>>>>> is > >>>>>>>> going to cause the ToC to look like: > >>>>>>>> > >>>>>>>> > >>>>>>>> Welcome > >>>>>>>> --High Level View > >>>>>>>> --Features > >>>>>>>> Get Started > >>>>>>>> > >>>>>>>> Even though you had expanded "Get Started" it will collapse when > >>>>> going > >>>>>> to > >>>>>>>> the Features page. That's because, without frames, each page is > its > >>>>>> own > >>>>>>>> HTML page. No state about the ToC is retained or shared. > >>>>>>>> > >>>>>>>> If folks are ok with that, I can probably get that to work. > >>>>>>>> > >>>>>>>> Thoughts? > >>>>>>>> -Alex > >>>>>>>> > >>>>>>> -- > >>>>>>> Andrew Wetmore > >>>>>>> > >>>>>>> http://cottage14.blogspot.com/ > >>>>>>> > >>>>>>> > >>>>>>> > >>>>>>> > >>>>>>> > >>>>>>> <https://www.avast.com/sig-email?utm_medium=email&utm_ > >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail> > >>>>>>> Virus-free. > >>>>>>> www.avast.com > >>>>>>> <https://www.avast.com/sig-email?utm_medium=email&utm_ > >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail> > >>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2> > >>>>>>> > >>>>>> > >>>>>> > >>>>>> > >>>>>> -- > >>>>>> Carlos Rovira > >>>>>> http://about.me/carlosrovira > >>>>>> > >>>>> > >>>>> > >>>>> > >>>>> -- > >>>>> Andrew Wetmore > >>>>> > >>>>> http://cottage14.blogspot.com/ > >>>>> > >>> > >>> > >> > > -- Andrew Wetmore http://cottage14.blogspot.com/
