BlogCategoryTag

Header

Footer

PreFooter

ProseBlock

Blog

SocialLinks

Prose

AnnouncementContextProvider

UnnamedGlobalGroupOfVariants2

Screen

Segment

Experiment

Experiment2

scale.com (Production)

plasmic-nav

plasmic-embed-css

plasmic-basic-components

plasmic-tabs

plasmic-cms

react-chartjs-2

react-slick

react-quill

Facundo Pepe

Engineering

Back on September 16th, we introduced you to our <a href="https://scale.com/blog/introducing-our-new-api-docs" rel="noopener noreferrer" target="_blank">new API Docs</a>. Today, we’re pleased to follow up the original announcement with further details on how we implemented this with Next.JS, Tailwind CSS, and ReadMe. Furthermore, rather than simply describing how we used each platform and framework, we have packaged together an example for you to implement and build off of <a href="https://github.com/scaleapi/custom-documentation-example" rel="noopener noreferrer" target="_blank">in this repository</a>.<h2>Some Context:</h2> At Scale AI, we are building the critical tools that make it easier to build and scale real-world AI systems. To provide our customers with the best experience possible on the Scale AI platform, we believe that a clear, simple, and memorable front-end, user interface, and user experience is critical. Scale’s design team has been hard at work building out a design system and improving customer-facing interfaces to bring front-end consistency across our platform. Most important to this effort was to implement the design system across our different applications. We decided to use Tailwind CSS as a CSS framework and CSS Modules as a way to add custom elements when some customization was needed. To ensure our website and applications were highly performant and loaded quickly, we chose to use Next.js as our react framework.<h2>Why Tailwind?</h2> Scale’s design team have used Next.js and styled-jsx as a way of providing CSS styling since the initial launch of our website. While this was fine when there were fewer pages on the website, it proved to be hard to scale and maintain a design system without proper documentation. At this point the team faced two options: we could either spend a lot of time creating and improving our own CSS and writing documentation for it, or we could use a CSS framework that could adapt to our needs. Since the Scale team prefers not to re-invent the wheel when it isn’t needed, we decided that using a CSS framework would yield the best results in the shortest period of time. Tailwind has allowed us to expedite the development of new layouts and pages while maintaining consistency across our website. Tailwind also has the advantage of having strong documentation behind it to support future development. Using Tailwind has also freed the team up to spend more time focusing on special details for each page like custom animations and interactions.<h2>Why Next.js?</h2> Next.js is one of the best React Frameworks out today. Since the launch of <a href="https://nextjs.org/blog/next-9-3#next-gen-static-site-generation-ssg-support" rel="noopener noreferrer" target="_blank">SGG support</a> in March, it’s a no brainer for a fast and performant website and API docs. Quoting them from their own <a href="https://nextjs.org/blog/next-9-3#next-gen-static-site-generation-ssg-support" rel="noopener noreferrer" target="_blank">blog post</a>:<img src="https://imagedelivery.net/wLbZE4_NzVVdgHc15St55g/4a743efa-0436-43a8-18b6-9368be8e8a00/public" alt="Next.js Quote"> Next.js’s API routes also proved to be helpful as we used this to retrieve the search values made by the user. More on their API Routes <a href="https://nextjs.org/docs/api-routes/introduction" rel="noopener noreferrer" target="_blank">here</a>. <h2>Why Readme?</h2> As we highlighted in our previous <a href="https://scale.com/blog/introducing-our-new-api-docs" rel="noopener noreferrer" target="_blank">blog post</a>, we chose ReadMe as the platform for our API documentation because ReadMe allowed us to: <ol><li> </li><li> Unify the API reference and the Customer Dashboard documentation into a</li><li> unified website.</li><li> </li><li> </li><li> Improve the developer experience. Instead of only showing static code</li><li> examples, ReadMe enables developers to submit API requests directly with</li><li> their Scale API key. ReadMe also has built in search functionality to make</li><li> it easier for developers to find specific topics.</li><li> </li><li> </li><li> Democratize the content creation process. Instead of editing raw markdown,</li><li> making a pull request, and then deploying to a server, we just had to</li><li> update the text we needed in the ReadMe UI. Ultimately, the ReadMe</li><li> platform provided a richer and more dynamic user experience.</li><li> </li></ol><h2> </h2><h2> Sharing our example code with the developer community</h2><h2> </h2> We developed the new API documentation during Scale’s Hackathon. We are incredibly proud of what we accomplished in just one week and we wanted to share our solution with anyone who is looking to solve a similar problem. Rather than simply providing a step-by-step instruction for this solution, we have packaged together an example for you in our <a href="https://github.com/scaleapi/custom-documentation-example" rel="noopener noreferrer" target="_blank">Github repo</a>. We hope this sample code allows you to build your own beautiful and customized documentation.

How to customize your API Documentation’s front-end leveraging cutting-edge platforms and frameworks.

Customizing API Documentation with Next.JS, Tailwind CSS, and ReadMe.

Quick Start Guide to Customized API Documentation

open-dataset-nucleus

slugs must be all lowercase. ie: ‘my-slug’

events-banner

This entry represents both interview quote highlight and interview chat highlight because of Builder limitations. Choose the fields that matches either of them.

interview-highlight

If it's selected, the author and quote fields will be taken, otherwise the chat fields. The default is for chat.

resources-download-model

transform-session

CTA to open the session. Leave blank if you don't want a cta for that session

Link for the CTA. Usually the link to the exchange session

blog-filter-type

event-transform-x-ticket

solution

homepage-quotes

logos

homepage-content

builder-debug

transfrom-x-in-person

event-model

Toggle if the event is featured. Featured events will be moved to the top of the list

guides-cta

summit-2023-partners

sales

z[deprecated] page

quotes

z[deprecated] compare

product

blog-category-model

announcement-banner

accelerate

Vercel Powered and Edge Computed OG Image. Preferred over og img file upload. If this field is non empty, it will take precedent over the uploaded file

summit-2023-speakers

homepage-resources

customers

Display order on the page /customers. Higher values show first

page-cross-product-webinar

interview

event-transform

Event model for new marketing events page

event-2-0

homepage-event

custom-fonts

transform-x-speaker

Be careful to not add any trailing white spaces to the slug. Slugs must be all lowercase. ie: ‘my-slug’

Order of the featured speakers displayed on the home page for transformX

z[deprecated] document-ai

summit-2023-agenda

event-converge

hosts

author

transform-x

Page: /In-Person. Section: Hero. Text: Title Text

Page: /In-Person. Section: Slider Card. Text: Title Text

Page: /In-Person. Section: Slider Card. Text: Card Body

Page: /In-Person. Section: Hero. Text: Tagline

open-dataset

z[deprecated] customers

URL redirections for Website. Disclaimer: takes 5~ min for each added or edited.

url-redirects

Use relative path. use `/blog/foo` not `https://scale.com/blog/foo`

legal

event

Optional second image intended to show on the grid view, should be a more squared image closer to 1:1 aspect ratio than the one used in the Cover field.

guides

z[deprecated] guides-old

z[deprecated] guides-lp

partners

blog-model

Option to list or not list this post in the Blog index. Enabled = not list in the index, Disabled = list in the index

Products

Government

Solutions

Resources

Customers

Pricing →

Quick Start Guide to Customized API Documentation

The future of your industry starts here.