On Sun, Jan 28, 2018 at 11:56 PM, Alex Harui <aha...@adobe.com.invalid> wrote:
> I'm still confused. I think we agreed to use GH Pages. AFAICT, GH Pages > uses Jekyll and Markdown. Jekyll is a general purpose static website generator. Gitbook is built specifically for documentation. > Jekyll expects a certain layout like templates > in a _layout folder. I have put a template in there. I don't understand > using a different production system that doesn't use Jekyll and its way of > laying out text. > You can publish to GH pages without using Jekyll: https://help.github.com/articles/using-a-static-site-generator-other-than-jekyll/ Here's how we can do it with Gitbook: http://sangsoonam.github.io/2016/08/02/publish-gitbook-to-your-github-pages.html Thanks, Om > > -Alex > > On 1/28/18, 11:11 PM, "omup...@gmail.com on behalf of OmPrakash Muppirala" > <omup...@gmail.com on behalf of bigosma...@gmail.com> wrote: > > >This does not use the Jekyll workflow. This uses the .md files directly. > > > >Thanks, > >Om > > > >On Jan 28, 2018 10:57 PM, "Alex Harui" <aha...@adobe.com.invalid> wrote: > > > >I don’t get it. There is a Jekyll template in our repo. The link I just > >clicked on did not appear to use it. > > > >-Alex > > > >On 1/28/18, 4:41 AM, "Andrew Wetmore" <cottag...@gmail.com> wrote: > > > >>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 <harbs.li...@gmail.com> > >>wrote: > >> > >>> BTW: > >>> > >>> That site has 3 levels in the table of contents: > >>> > >>>https://na01.safelinks.protection.outlook.com/?url= > https%3A%2F%2Fredux.j > >>>s > >>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html& > data=02%7C0 > >>>1 > >>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c > 8547%7Cfa7b1b5a7b344 > >>>3 > >>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata= > 4Bdy4FThikLGQukS0S > >>>S > >>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0 < > >>> > >>>https://na01.safelinks.protection.outlook.com/?url= > https%3A%2F%2Fredux.j > >>>s > >>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html& > data=02%7C0 > >>>1 > >>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c > 8547%7Cfa7b1b5a7b344 > >>>3 > >>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata= > 4Bdy4FThikLGQukS0S > >>>S > >>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0> > >>> > >>> > On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala > >>><bigosma...@gmail.com> > >>> wrote: > >>> > > >>> > Here is a very good example of what the end product would look like: > >>> > > >>>https://na01.safelinks.protection.outlook.com/?url= > https%3A%2F%2Fredux.j > >>>s > >>>.org%2F&data=02%7C01%7Caharui%40adobe.com% > 7Ce35c7c4743804324141308d5664c > >>>8 > >>>547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0% > 7C636527401200834465&sdat > >>>a > >>>=GrTlTr5PCqHK6qS9pg9dKcKyRtO6BJU1xpxLGzWYOsY%3D&reserved=0 > >>> > > >>> > Thanks, > >>> > Om > >>> > > >>> > On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala < > >>> bigosma...@gmail.com> > >>> > wrote: > >>> > > >>> >> > >>> >> > >>> >> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <harbs.li...@gmail.com> > >>> 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 < > >>> bigosma...@gmail.com> > >>> >>> wrote: > >>> >>>> > >>> >>>> I've been playing around with the tool: GitBook > >>>[https://na01.safelinks.protection.outlook.com/?url= > www.gitbooks.io&data > >>>= > >>>02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c > 8547%7Cfa7b1b > >>>5 > >>>a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465& > sdata=VI3BEHW9v7G > >>>P > >>>nAlTOg2gEp%2FgLrF61UFUShsrxY1wG7I%3D&reserved=0] > >>> >>>> 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://na01.safelinks.protection.outlook.com/?url= > https%3A%2F%2Fbigosma > >>>l > >>>lm.gitbooks.io%2Froyale-docs-test2%2Fcontent%2Fv%2F& > data=02%7C01%7Caharu > >>>i > >>>%40adobe.com%7Ce35c7c4743804324141308d5664c > 8547%7Cfa7b1b5a7b34438794aed2 > >>>c > >>>178decee1%7C0%7C0%7C636527401200834465&sdata= > wYN9q4TD9UFz8rwXmzoh8QDc16E > >>>n > >>>Q64NDLMa4XKvMdg%3D&reserved=0 > >>> >>> 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://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub > . > >>>c > >>>om%2FGitbookIO%2Fgitbook&data=02%7C01%7Caharui%40adobe.com > %7Ce35c7c47438 > >>>0 > >>>4324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178de > cee1%7C0%7C0%7C636527 > >>>4 > >>>01200834465&sdata=9yrCy9F6C7auYCI%2FEjfdLi8gTkkma%2FN4rURUrFDU% > 2FZI%3D&r > >>>e > >>>served=0) > >>> >>> 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 > >>><cottag...@gmail.com> > >>> >>> 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 < > >>> >>> carlosrov...@apache.org> > >>> >>>>> 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 <cottag...@gmail.com>: > >>> >>>>>> > >>> >>>>>>> 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 > >>> <aha...@adobe.com.invalid > >>> >>>> > >>> >>>>>>> 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 > >>> >>>>>>> > >>> >>>>>>> > >>>https://na01.safelinks.protection.outlook.com/?url= > http%3A%2F%2Fcottage1 > >>>4 > >>>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com% > 7Ce35c7c4743804324141 > >>>3 > >>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178de > cee1%7C0%7C0%7C63652740120083 > >>>4 > >>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0 > >>> >>>>>>> > >>> >>>>>>> > >>> >>>>>>> > >>> >>>>>>> > >>> >>>>>>> > >>> >>>>>>> > >>><https://na01.safelinks.protection.outlook.com/?url= > https%3A%2F%2Fwww.av > >>>a > >>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02% > 7C01%7Caharui%40a > >>>d > >>>obe.com%7Ce35c7c4743804324141308d5664c8547% > 7Cfa7b1b5a7b34438794aed2c178d > >>>e > >>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5j > mB > >>>P > >>>S86IdsRNiQ%3D&reserved=0 > >>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail> > >>> >>>>>>> Virus-free. > >>> >>>>>>> > >>>https://na01.safelinks.protection.outlook.com/?url= > www.avast.com&data=02 > >>>% > >>>7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c > 8547%7Cfa7b1b5a7 > >>>b > >>>34438794aed2c178decee1%7C0%7C0%7C636527401200834465& > sdata=zkLsd1ijA9LimW > >>>6 > >>>%2F3Kfze8CwM%2Fn2ty8Twehti%2B8QbXA%3D&reserved=0 > >>> >>>>>>> > >>><https://na01.safelinks.protection.outlook.com/?url= > https%3A%2F%2Fwww.av > >>>a > >>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02% > 7C01%7Caharui%40a > >>>d > >>>obe.com%7Ce35c7c4743804324141308d5664c8547% > 7Cfa7b1b5a7b34438794aed2c178d > >>>e > >>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5j > mB > >>>P > >>>S86IdsRNiQ%3D&reserved=0 > >>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail> > >>> >>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2> > >>> >>>>>>> > >>> >>>>>> > >>> >>>>>> > >>> >>>>>> > >>> >>>>>> -- > >>> >>>>>> Carlos Rovira > >>> >>>>>> > >>>https://na01.safelinks.protection.outlook.com/?url= > http%3A%2F%2Fabout.me > >>>% > >>>2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com% > 7Ce35c7c474380432414130 > >>>8 > >>>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0% > 7C6365274012008344 > >>>6 > >>>5&sdata=3LH%2BI93bLwNWxoOGx6eo6A2MBQaxxUMrNrufjXIh6Bo%3D&reserved=0 > >>> >>>>>> > >>> >>>>> > >>> >>>>> > >>> >>>>> > >>> >>>>> -- > >>> >>>>> Andrew Wetmore > >>> >>>>> > >>> >>>>> > >>>https://na01.safelinks.protection.outlook.com/?url= > http%3A%2F%2Fcottage1 > >>>4 > >>>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com% > 7Ce35c7c4743804324141 > >>>3 > >>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178de > cee1%7C0%7C0%7C63652740120083 > >>>4 > >>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0 > >>> >>>>> > >>> >>> > >>> >>> > >>> >> > >>> > >>> > >> > >> > >>-- > >>Andrew Wetmore > >> > >>https://na01.safelinks.protection.outlook.com/?url= > http%3A%2F%2Fcottage14 > >>. > >>blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com% > 7Ce35c7c474380432414130 > >>8 > >>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0% > 7C63652740120083446 > >>5 > >>&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0 > >
