OK, so to be clear, you are proposing replacing Jekyll with Gitbook. It looked to me that Gitbook doesn't have as smooth a publishing mechanism. I'll go with whatever the majority wants to do, but I really just want to focus on content instead of debating the merits of alternatives to Gitbook. We are already many hours in on Jekyll. I think it works well enough. And we can control every pixel on the screen.
My 2 cents, -Alex On 1/29/18, 12:23 AM, "omup...@gmail.com on behalf of OmPrakash Muppirala" <omup...@gmail.com on behalf of bigosma...@gmail.com> wrote: >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://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fhelp.gith >ub.com%2Farticles%2Fusing-a-static-site-generator-other-than-jekyll%2F&dat >a=02%7C01%7Caharui%40adobe.com%7C0ebe0d56d8294e04a6ee08d566f1aaa1%7Cfa7b1b >5a7b34438794aed2c178decee1%7C0%7C0%7C636528110492215042&sdata=GsI6eXK7%2F2 >zKtKHD2dsCQVQ5QbKwdyk4BeP4PWdGbKY%3D&reserved=0 > >Here's how we can do it with Gitbook: >https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fsangsoonam >.github.io%2F2016%2F08%2F02%2Fpublish-gitbook-to-your-github-pages.html&da >ta=02%7C01%7Caharui%40adobe.com%7C0ebe0d56d8294e04a6ee08d566f1aaa1%7Cfa7b1 >b5a7b34438794aed2c178decee1%7C0%7C0%7C636528110492215042&sdata=iVvLnTi96t% >2BB9RzzJMbcga3Vk1vQymNPOSAC0y%2BzKoo%3D&reserved=0 > >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= >> >>https://na01.safelinks.protection.outlook.com/?url=www.gitbooks.io&data=0 >>2%7C01%7Caharui%40adobe.com%7C0ebe0d56d8294e04a6ee08d566f1aaa1%7Cfa7b1b5a >>7b34438794aed2c178decee1%7C0%7C0%7C636528110492215042&sdata=FnygcKm4rNdnS >>KgB5Ig22g8RK8%2FJ4TBu6fFkFiyGXac%3D&reserved=0&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%2Fgithu >>>>>b >> . >> >>>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= >> >>https://na01.safelinks.protection.outlook.com/?url=www.avast.com&data=02% >>7C01%7Caharui%40adobe.com%7C0ebe0d56d8294e04a6ee08d566f1aaa1%7Cfa7b1b5a7b >>34438794aed2c178decee1%7C0%7C0%7C636528110492215042&sdata=nJd8J9PJajaOVPd >>3yRA%2FOe4P1p6BaUUedsJ1MwulX30%3D&reserved=0&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 >> >>
