Skip to content

Customization

Jump to bottom
Ashton Eby edited this page May 22, 2019 · 3 revisions

After deployment, you can overwrite certain files in the S3 bucket to update images, styling and the content of specific pages. All customizations live in the custom-content folder of the bucket defined by the DevPortalSiteS3BucketName parameter in the sam deploy command (default value "custom-prefix-dev-portal-static-assets").

By default, on upload to the S3 bucket, the permissions are restricted. Make sure that "Everyone" has Read permissions to the files in the S3 bucket otherwise you might see some components not displaying properly.

By default, the easy customizations described below won't be updated by subsequent deployments. This makes it safe to deploy architectural changes to the Developer Portal without overwriting your branding and content changes. To override this behavior, see Advanced Customization below.

Images

You can update the logo that appears in the navbar, the image that appears on the Home page, and the images that appear for each api on the API details pages.

All images must be .png.

  • /custom-content/nav-logo.png

    The logo in that appears in the navbar. Replace it to use your own image.

  • /custom-content/home-image.png

    Primary image displayed on the Home page. Replace it to use your own image.

  • /custom-content/api-logos/default.png

    The default image used when a specific api image is not provided. Replace it to use your own image.

  • /custom-content/api-logos/{apiId}_{stage}.png

    A custom image for a given API and Stage. If provided will be displayed instead of the default.png

    e.g. /custom-content/api-logos/s8df5s3dd_Prod.png

Styling

Replace the /custom-content/styles.css with your own CSS Styling. Note that this stylesheet is loaded before all other styles in the project. Be sure to make sure your styles do not collide.

Content

Content on the Home page, the Getting Started page can be modified by updating the markdown files in /custom-content/content-fragments.

Each file begins with a yaml front matter block. This front matter is used to fill in data beyond the content of the page.

---
title: Navbar Header # Display in the navbar 
header: Main Page Header # Main headline on the page
---

Your content starts here.

The content of the page is rendered using GitHub-flavoured markdown. You can also nest HTML inside each markdown fragment if you need more complex layouts.

# My Content Header!

Some content content...

[<button>A button that's a link!</button>](https://aws.amazon.com/api-gateway/)

The Home page takes the following front matter:

  • title: Text that appears in the navbar.
  • header: Main headline on the Home page.
  • tagline: Secondary headline on the Home page.
  • gettingStartedButton: Text of the "Getting Started" button.
  • apiListButton: Text of the "Our APIs" button.

The APIs page takes the following front matter:

  • title: Text that appears in the navbar.

The GettingStarted page takes the following front matter:

  • title: Text that appears in the navbar.

Advanced customization

In addition to the easy customization described above, you can make changes in your cloned copy of the repository, version with git, and package & deploy with SAM. You must include the StaticAssetRebuildToken as part of the deployment.

To pull in new versions of the dev portal, merge or rebase in the upstream changes.

By default, the easy customizations described above won't be updated by subsequent deployments. If you would prefer to overwrite all files in the s3 bucket on a deploy, pass the StaticAssetRebuildMode=overwrite-content argument to your sam deploy command in addition to the StaticAssetRebuildToken. See Advanced Customization below.

Clone this wiki locally