royale-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gabe Harbs <>
Subject Re: Help docs ToC and links
Date Fri, 26 Jan 2018 11:27:11 GMT
I’m trying to find my bearings after following lightly for a couple of weeks.

I’m really excited by all the work that’s been going on vis a vis docs lately. I think
it’s really important work and really glad it’s happening.

How do I view the current status of the work on docs? I see there’s a develop branch on
the docs repo, but I’m not sure how to actually view that. Is there a URL that Jekyll outputs
changes to? Is it built locally, and if yes how? How is changes actually published by Jekyll
to the docs site?


> On Jan 26, 2018, at 9:14 AM, Alex Harui <> wrote:
> OK, I figured out how to generate the ToC from a JSON file
> (_data/toc.json).  Basically, it is a hierarchical structure.  Each ToC
> entry is a JSON Object with a path property and an optional children array
> of other ToC entries.
> The title and links are pulled from the site information gathered by
> Jekyll, so you won't see ToC entries on the page for entries in the
> toc.json that don't have an actual file.  Which also means that if you
> don't match the path to the actual file name it won't show either.  Make
> sure you have your capital letters and everything correct.
> I also figured you were asleep at this hour so I did the license sweep.
> Make sure you sync up any local working copies before making more changes.
> On 1/25/18, 6:51 PM, "Alex Harui" <> wrote:
>> OK, I saw your other email about more ToC changes coming.  I think I am
>> going to try to generate the ToC.
>> -Alex
>> On 1/25/18, 6:32 PM, "Alex Harui" <> wrote:
>>> On 1/25/18, 4:11 PM, "Andrew Wetmore" <> wrote:
>>>> Hi:
>>>> I have not been touching the ToC file because it looks very easy to get
>>>> wrong. 
>>> Yeah, I was fiddling with the ToC and thinking the same thing.  I'm
>>> wondering how many more changes to the ToC we'll be doing.  If it is just
>>> a few more to implement your proposed ToC, we could just keep the current
>>> way and fix the small things as we find it.  If we think we're going to
>>> be
>>> adding new entries and/or renaming entries, maybe it is worth it for me
>>> to
>>> try to spend a day making the ToC "generate" from the .MD files.  We
>>> would
>>> probably dictate the organization of the ToC in a JSON file, but the
>>> entries would be less error prone.  Maybe like:
>>> { "toc": [ "" : [ "welcome/" : [] ,
>>>                         "welcome/": [
>>> "welcome/features/" ...
>>>          "" : ["get-started/" ...
>>> Essentially, a hierarchical object that just lists the file names in the
>>> order you want them to appear in the ToC.  I think I can get Jekyll to
>>> generate the ToC by using the page titles.
>>>> I have also not been inserting links from one .md page to another
>>>> because I am not clear whether we are using relative or absolute links
>>>> (not
>>>> sure, for instance, whether there is a performance benefit of one over
>>>> the
>>>> other...).
>>> In the .md files, links have to be a full path without the leading slash.
>>> So to link to /welcome/features/, you would use
>>> [as3](welcome/features/as3.html)
>>>> Also, when we link out from the help docs to another section of the
>>>> Royale
>>>> site, or any other resource, we should pop a new browser window, not
>>>> take
>>>> the reader away from the help docs. Is there a standard way to declare
>>>> that
>>>> when writing a link in markdown? Is it the same as in HTML
>>>> ("target=_blank")?
>>> I had to look it up.  The syntax is:
>>>> [as3](welcome/features/as3.html){:target='_blank'}
>>> I just modified and tested it and it seemed to work.
>>> -Alex

View raw message