Community Docs Contributor Guide for Viewport/Confluence

Overview: How does it work?

Scroll Viewport is a Confluence App that allows you to quickly publish Confluence pages in a styled Help website. You write and edit your content in Confluence, structure individual pages into a page tree hierarchy, and then push content to Viewport. Viewport builds a static site from one or more Confluence spaces, preserving your page tree hierarchy as the site architecture.

Changes made to a Confluence space will not go live on Viewport until you trigger an update from a Viewport dashboard. This way, you can work on content behind the scenes and publish it to your public help center when it is ready.

Most use cases at Sage will use a single Confluence space connected to a single Viewport Help website. This allows each help website to be branded and formatted individually (e.g. the AD Knowledge Portal doc site will look different than the NF Portal doc website). It is possible to combine multiple spaces into a single Viewport site, however in this case they will all share the same branding and layout options.

Editing in Confluence

• Navigate to your Confluence space.

  • If you are adding a new article, create a new page by clicking the blue Create icon at the top of the screen. Drag and drop the new page to move it around in the page tree hierarchy. To “promote” a page so that it is no longer a sub-page, drag and drop it to the left side of the page tree menu.

• On the page where you want to add/edit content, click the pencil icon () to enter the Confluence editor. Add your content, tag reviewers, and comment in-line until the content is final.

• Note that you should not use the H1 header level, as this heading will not populate the article table of contents in Viewport. Start your headers with H2 and below.

• Publish your content from the Confluence editor by clicking the blue “Publish” button in the upper right. The new content is now live on Confluence, but it is not yet visible on the Viewport site. See the section, Updating your Viewport site, below for more info on how to push your changes to the live doc website.

Adding links to articles or article sections

You may want to add a link to an external website to one of your articles. Or you may want to add a link from one article to another on your Viewport site. To do so, go to the Confluence page you want to edit and click the pencil icon () to enter editing mode. Select the text you want to associate with a link, then use the link button () in the Confluence editor to add a URL.

For external links, you can paste a URL directly into this pop-up window (e.g. enter www.sagebionetworks.org).

For links from one article to another, you can use the pop-up window to search for other articles in Confluence (red box, below), OR you can choose from a list of recently viewed articles (red arrow). Select the article you want to link to and hit Enter. Viewport will automatically convert this Confluence link to the appropriate URL for external users when you update your doc site.

Open

IMPORTANT: Linking to another Confluence article on your Viewport site will ONLY work if the article is also in the same Confluence space that is driving your Viewport site. Both articles must be in the same Confluence source space. For example, if you are working in a community docs space, you can link to any other article in that space and Viewport will convert the URL appropriately. If you want to link to a Synapse docs article (which is located in Confluence but in a different space than your community docs), you must use the public URL for that page when creating a link (e.g. help.synapse.org/articlename, not the Confluence internal reference). The Viewport app can only see content that is within your community doc space, and it will not convert Confluence content from other spaces into your doc site.

To add a link to a specific section of another article in your Confluence space, go to the section you want to link to and copy the section link next to the section header name. If you add this URL as a link in your text, Viewport will pick up the Confluence URL and convert it to the appropriate Viewport URL for external users. Note that Viewport will only recognize and convert section and article links from your doc space, but not from other Confluence spaces (even if they are driving other Viewport sites).

Open

To add a link to a specific section of the same article in your Confluence space, go to the section you want to link to and copy the section link next to the section header name. If you add this URL as a link in your text, Viewport will NOT convert it to the appropriate Viewport URL correctly. You will have to manually adjust the section of the URL after the # to include the page title and section title (without hyphens) as shown in this example:

Link before manual fix:

https://help.adknowledgeportal.org/apd/Agora-Data-and-Methods.2662760477.html#LFQ-Data-and-Methods

Link after manual fix:
https://sagebionetworks.jira.com/wiki/spaces/APD/pages/2662760477/Agora+Data+and+Methods#AgoraDataandMethods-LFQDataandMethods

Adding downloads and attachments

• To add a download link to a page (e.g. a pdf, template, or other file that users need to download), add your file as an attachment to the Confluence page. From the main page view (not the Confluence editor), click the three dots at the top right of the screen and select attachments from the dropdown:

• Upload your files.

• In the Attachments view, right click on the name of the attachments and select Copy Linked Address.

• Go to your page and add a link to the desired text. Paste in the attachment link as the URL. Viewport will render the Confluence URL into a file download for external users.

• Note: Viewport can only render links for items that are within the associated Confluence space. Items outside of that space (links or attachments from other spaces) will not render correctly on your Viewport site.

Adding images

You can add images to your Confluence pages by using the Insert Image button in the Confluence editing toolbar ( ). Any images that you embed into a Confluence page will be rendered on your Viewport site. A few things to keep in mind:

• Viewport will center all images

• You cannot resize images in Viewport. If you upload an image to Confluence and it appears too large or too small on your Viewport site, you need to adjust the image file size and re-upload it to Confluence.

• You can change the size of an image within Confluence by dragging a corner to expand or shrink the image, but these changes will not be reflected on your Viewport site.

Reviewing in Confluence

Many common reviewing features from Google docs are available in Confluence:

• To comment on a page, highlight the text where you wish to make a comment and look for the pop-up options. Select Comment. You can also tag people using an @ mention so they will be notified automatically. Comments on a Confluence page will not be published in Viewport.

• To make changes to a document, click the pencil icon at the top of the Confluence page ( ) to enter editing mode. Edit the doc and click the blue Publish button to save your changes to Confluence. You can also publish with a version comment by clicking the three dots in the upper right hand corner () and select Publish with a version comment.

• To see version history for a page, make sure you are on the main page view (to exit editing mode, click Publish or Close to get back to the main page view). Click on the three dots at the upper right corner () and then select Page History.

• In Page history, you can view all versions of the page, who created them, and any version comments. You can compare 2 versions by selecting them and clicking Compare Selected Versions. You can also Restore or Delete previous versions.

Updating your Viewport site

When you work in Confluence, edits to a page do NOT immediately go live to your Viewport site. You must manually push changes from Confluence to the Viewport site in order for them to be publicly visible. This allows you to work on documents “behind the scenes” and publish them only when you are ready.

• To publish content to Viewport, navigate to the Apps tab at the top of your screen, and select Scroll Viewport. If you do not see Viewport in the Apps menu, contact IT and ask to be added to the scroll-viewport-admins group (this can only be done by a Jira sys admin).

• Note: you may need to reload the Viewport dashboard once or twice for it to appear (this is an iframe bug that Confluence is addressing).

• Select your Viewport site from the list.

• Viewport will recognize if any pages have changed since the previous build. You can click on the changelog to view the pages that have changed. From the changelog pop-up window, you can click back to a specific Confluence page if you need to see the change in-line.

• If everything looks good, click Update site

• Viewport will build the static site, pulling all of the pages in your Confluence space into your Viewport site.

• You can preview your site before going live, or click Go live to publish your changes to the web.

Using Confluence labels with Viewport

You can add specific labels to a Confluence page that act like instructions for Viewport. Depending on the label you add, you can tell Viewport to either hide pages, or create certain homepage elements with them (pinned pages, call to action button).

Hiding Confluence pages from Viewport

To exclude a page from the Viewport navigation tree and search, add the label scroll-help-center-exclude-page to a page to hide it from the public site. Adding this tag to a top level page in Confluence will also exclude all of the child pages automatically. Note that the excluded page will still be built as a part of the Viewport site, but the url will not be publicly surfaced in any way. Therefore, the page is still viewable by external users but only if they are given the URL. For more info, check out the Viewport help docs.

• Example use case #1: create an “Internal docs” page tree for internal SOPs or other information for your team that you don’t want to expose to external users.

• Example use case #2: use the tag to hide specific pages from the navigation that are not relevant for most external users. For example, if you have a specific set of docs for funders, you can provide a “private” link to just those groups.

Pin pages to your Viewport homepage

You can define “pinned” articles on your homepage with the scroll-help-center-pinned-page label. You can label up to 3 articles (e.g. scroll-help-center-pinned-page-1, scroll-help-center-pinned-page-2). Read more about how to use this label here.

Create a call to action button on your Viewport homepage

You can also create a button with customized text that will link to a specific article on your homepage. Use the scroll-help-center-cta-page tag and customize the button text in the theme editor. Read more here.

Configuring look and feel of your Viewport site

• Many aspects of the homepage layout can be changed from your Viewport dashboard. Navigate to the Viewport dashboard for your site (see above, from Confluence, Apps → Scroll Viewport → Your Site Name)

• Click on Edit theme at the top of the dashboard.

• The Theme editor allows you to:

  • change the banner, text, and icon colors

  • upload and select a new banner image, favicon, and site logo

  • select or de-select homepage components (Pinned Articles, News)

  • add, remove, or edit header and footer links

  • choose from 3 different master layouts (hero, detail, and article)

• For more information on how to configure your homepage, consult the Viewport help docs.

Creating a new link in the Viewport site header or footer

You may want to create a link in the Viewport header or footer so that certain external URLs or Confluence pages are always accessible for your readers. Viewport allows you space to designate up to 5 links.

• Navigate to the Viewport dashboard for your site (see above, from Confluence, Apps → Scroll Viewport → Your Site Name)

• At the top of the dashboard, select Edit theme.

• Select Templates, then Header or Footer. Scroll down to the Links section.

• To add a new link, click Add new link, then enter the text and URL. You can drag and drop each link to re-order it at the header and the site preview will update to show you how your changes look. Click Save.

• Update your site for your changes to go live.

Changing your homepage description

Your Confluence Space Overview page is used to drive the Viewport homepage description, so only add information that is external-facing to your space Overview page. You can also customize the site title and welcome/call-to-action messages via your Overview page. Do not use this space to add instructions for internal Sage teammates unless you want it on your Viewport site!

• To find your Confluence space overview page look in the left side menu toward the top.

• Click on the Overview page, then enter edit mode by clicking the pencil icon () at the top right. The page title becomes you Viewport site title. Text in the excerpt macro will be used for the site description and can be edited here.

• In Confluence you will see:

• On the Viewport site you will see:

Tips and Tricks

• To make it easy for other contributors to add pages to your space, create Confluence templates for different types of articles (e.g. How-To, Tutorial, Troubleshooting, Reference, etc).

• Click the eye icon at the top of the page to start watching it. You’ll get updates whenever anyone makes a change.

• Use the Include macro to create excerpts of text that can be re-used throughout your site. If you need to edit this text, you only need to edit in a single location and the change is populated wherever the text has been re-used.

  • A common use case is to use Includes to add an article footer at the bottom of every page (your Include could be part of your template). The footer contains contact information and/or a link so users can provide feedback on your docs.

• Browse the complete list of Confluence macros that Viewport supports here. Note that not all Confluence macros will be rendered correctly in Viewport, and some are redundant with features that Viewport already offers.