Site Documentation solution

I need to create a new section of an existing RW site that houses notes in markdown text. There needs to be a menu structure that is easy to navigate and will also show where you are. The notes are topical in nature and the navigation needs to reflect this. I would prefer a separate navigation down the side, leaving the main nav across the top untouched. There will be some 1200 notes. I was thinking of creating this in a separate RW project that uses a subfolder off the main domain as its root, with offsite pages creating the menu to link back.

Any idea of a solution for this?

If you’re using Foundry this might be something that would help out.

In that thread I offer up a free project file that is a rough duplication of my documentation pages.

Thanks Adam,

I did look at partitions, but the navigation does not show where you are. You click on a page and the navigation does not remain there nor indicate where you are. For a topical site where people may well want to browse through, this would not work.

Not sure what you mean. Partitions has nothing to do with the navigation.

That’s my problem. I need the active page in partitions to be linked to the navigation. In the same way the main nav shows you the active page that you are on. I will have some 1200 pages and don’t want people to get lost from where they are, as well as them having the ability to easily navigate to the next note in the navigation.

Hope that makes sense.

I don’t own the stack but this might work?

and there’s a free demo.

You can use any navigation you like within Partitions. Each item is its own page, just as on my site.

I opted for using Vertical Nav stack for my side navigation, but you can use anything you like. As for getting lost – if your pages are well marked there’s no way a user will not know what page they’re on. Take this one for example:

You can’t miss that you’re on the Navigation Bar documentation page, right? Give your visitors some credit. :wink:

That said, do what you like, I was just offering up an example of a project.

The difficulty is though, that in the navigation it doesn’t show where the Navigation Bar page is. So the user has to look for it. I was thinking more of a solution that shows exactly where you are in the navigation as Stripe’s API page does :

This is far easier to navigate and there’s no need to guess where you are.

Then use a navigation stack that offers that feature.

Vertical Navigation can do that but you need to set it manually, which I’m guessing you won’t want to do. But you can use any navigation stack you like, as I mentioned above.

Therein lies the problem. I know you can set a specific page to be active in the vertical nav stack, but you cannot seem to link the nav to a specific page so that the nav item becomes active when you’re on that page.

You’re not tied into using the Vertical Navigation stack. Use any navigation stack you like. :slight_smile:

@svsmailus By 1200 notes do you also mean 1200 pages? Or can the notes all be on one page and the navigation scroll down to the correct one? If so there’s a pretty easy solution. But not sure exactly what you are trying to accomplish with notes organization.

I’m thinking they may need to be separate pages as I want to link it to something like DuckDuckgo search and having all notes on one page might create a search results problem. Not sure though!

Either way it’s a big chore!

However it is possible to create 1 markdown page with within page scrolling that is automatic once you’ve set up the correct stack. Then where the menu/links gets displayed is up to you. I suppose the notes could go into groups and folks only scroll down to the groups.

I’m just guessing as I’m not sure what you want really looks like. But for very convenient within page scrolling with a table of contents check out Stacks4Stacks Jump stack:

You can then display the automated links within page via something like the Glider stack (or others) in a sidebar area.

@robbeattie Already mentioned this option. Especially read about the Table of Contents generation fairly far down the page. That’s the key. (The previous/next stuff can be ignored and does not need to be implemented.)

Thanks guys, that is helpful. I’m wondering if RW is the best tool for this one. Ultimately, I’d like it to look and operate similarly to the image I posted from the Strip API page. I had thought this would be an easy no brainer, all text in markdown, but alas these things never are! :stuck_out_tongue_winking_eye:

You can get awfully close to that Stripe look with Jump (for auto-generated TOC) and another stack/column to “hold” the TOC. The thing that has me puzzled is the Stripe example has way less than 1200 pages/locations. But what they’ve done can definitely be accomplished with RW, Jump, and how you choose to place the TOC using one page.Realistically create 2 columns: one for the TOC div (see Jump) and one for the contents. Using well organized Markdown headers will be the key.

Hi Simon (@svsmailus),

Sorry I didn’t reply sooner, I was on Mobile when this post was around and I know I’m late on replying to this post. I bookmarked it and now just came back. I have some thoughts, first off 1200+ notes is really going to be way too much for a single page. You mentioned search engines as being a concern, and not only will it make it next to impossible to get links to the exact note on the page, it would make it difficult for the search engine to determine what the page is about.

I don’t know the content and how similar the notes are to one another or how long they are, but navigation is only one concern. The sidebar like stripe uses works well, but stripe isn’t displaying near 1200 individual subjects. Honestly, I don’t find there api-page easy to navigate at all. I’d probably want a look more like the Bootstrap documentation site, where if I’m looking for items about layout I have a section on a layout that expands. Similar to the Foundry documentation that’s referenced on this post.

So organizing these 1200 notes is probably the hardest part.

Now RapidWeaver is great, and yes, there are folks that have figured out ways to make it do things that it really isn’t the best of class at doing. You were “wondering if RW is the best tool for this one”, and my answer is it depends.

You didn’t say if over one person is going to be editing these notes? Are the notes going though regular edits (adding, deleting and changing) or is this stagnant content, once and done? How are users going to go through 1200 notes? Do you need a search function? One thing you might look at (outside of RW) would be MediaWiki. It offers the sidebar navigation you like, has a built-in search, allows multiple users to edit and is familiar to most users (Wikipedia uses it) and it’s free. Will Woodgate has an article on this you might have a look at.

Now the other option you liked was the one that Adam uses with the Foundry documentation (Vertical Navigation stack). The only issue you had with that was that it didn’t automatically make the active page. I ran across some JavaScript of mine I had used for a similar problem, and just spent a little time changing it to work with the Foundry Vertical Navigation stack.

This will allow things up with the project that Adam offered above, it will automatically mark the current page as active(Open the section as well). I just tested it and it seems to work fine.

  • You need to have tidy links turned on (the default).
  • It’s best to set the page using the “page link” (not URL) in the RapidWeaver link dialog. It should work with a full URL but that won’t work in preview.
    2021-01-09_12-07-40

It will mark any link within the Foundry Vertical Navigation stack were the URL is the current page. All sections that contain the matching URL will be opened and the link will be marked active.

I have a test site out right now if you want to have a look. It’s just a stripped down version of Adams project file from above.

Just add this Javascript to the site wide code section:

And here is the code About 53 lines:

function extractTidyURL(urlIn) {
    const endSlash = urlIn.lastIndexOf("/");
    if (endSlash == (urlIn.length - 1)) {
        return urlIn;
    } else {
        const newURL = urlIn.slice(0, (endSlash + 1));
        return newURL;
    }
}
function readyFn() {
    const navbarNav = document.querySelectorAll("ul[id$='foundry-vert-menu']"); /* Find All vert menus on page */
    const currentURL = extractTidyURL(window.location.href);
    if (navbarNav && navbarNav.len != 0) {
        navbarNav.forEach(NavBarElement => {
            const anchorsNode = NavBarElement.querySelectorAll('a'); /* get Anchors for each Menu */
            if (anchorsNode && anchorsNode.len != 0) {
                anchorsNode.forEach(element => {
                    const theHref = element.attributes.href.value; /* Look for same page  href */
                    if ((theHref === './') || (theHref == currentURL)) {
                        element.parentNode.classList.add('active'); /* Add active class to LI */
                        const NavBarColapseNode = NavBarElement.querySelector('h3.collapsed'); /* Find Heading node */
                        if (NavBarColapseNode && NavBarColapseNode.len != 0) {
                            NavBarColapseNode.classList.remove('collapsed'); /* swap classes */
                            NavBarColapseNode.classList.add('expanded');
                            const navBarArrowNode = NavBarColapseNode.querySelector('a.arrow-btn'); /*  Find Achor with arrow */
                            if (navBarArrowNode && navBarArrowNode.len != 0) {
                                navBarArrowNode.classList.add('expanded'); /* add expanded class */
                            } /* end  (navBarArrowNode.len != 0)*/
                        } /* end (NavBarColapseNode.len != 0) */
                        const ULNode = element.parentNode.parentNode; /* get UL node */
                        if (ULNode && ULNode.len != 0) {
                            const LIactNode = ULNode.querySelectorAll('li'); /* Bump thru LI snd set display */
                            if (LIactNode && LIactNode.len != 0) {
                                LIactNode.forEach(element => {
                                    element.style.display = 'block';
                                }); /* end LIactNode.forEach(element =>*/
                            } /* end if(LIactNode.len !=0)*/
                        } /* end if (ULNode.len !=0) */
                    } /* end if (theHref === './')*/
                }); /* end anchorsNode.forEach(element =>*/
            } /* end if (anchorsNode.len !=0) */
        }); /* end navbarNav.forEach(element => {*/
    } /* end if (navbarNav.len !=0) */
} /* end readyFn */
if (document.readyState !== 'loading') {
    readyFn();
} else {
    document.addEventListener('readystatechange', event => {
        if ((event.target.readyState === 'interactive')) {
            readyFn();
        }
    });
}
6 Likes

@teefers Wow, this looks wonderful! I don’t know if it will solve @svsmailus 's issue as we don’t know all the details. But … this JS is fantastic! I hope it is useful for Simon. And I’m certainly going to take advantage of it for a future project: I love Adam’s Vertical Navigation stack.

Again, many thanks.

1 Like

Too funny. I have coded in auto URL detection for Vertical Nav that is waiting for the next update. Nicely done with your implementation @teefers

After the discussion here I thought I should add it in to the stack. In addition there’s also some more styling options that will be available too. :slight_smile:

6 Likes

SvsMailus,
For your problem, I think you should look at google/sites… It is free, already hosted and has lots of features.
I mean… HTML was invented to write manuals at CERN some years ago… Rapidweaver, which I am a big fan of… don’t get me wrong… Is an overkill for you problem…