commercetools / commercetools-docs-kit Goto Github PK
View Code? Open in Web Editor NEWTools and components for developing Documentation websites 🛠
Home Page: https://docs-kit.commercetools.vercel.app
License: MIT License
Tools and components for developing Documentation websites 🛠
Home Page: https://docs-kit.commercetools.vercel.app
License: MIT License
When writing Dates, we prefer an "international long format" like "2020 January 20" over the USA convention coded into the Google Style Guide we base on.
Additionally, formats with the Months spelled out should always be preferred over numeric-only formats to make sure the date is free of any ambiguities. So writing "December 12th 2012" and writing "2012-12-12", "2012 / 12 / 12" , "12.12.2012", "12.12.12" should all be warnings. The warning text should be separate, so we need two separate Rules
(Time not handled here, that's a separate decision)
The smoke test sites currently have a valid google analytics ID configured, which is not desirable because that way they will track traffic into the GA project of the actual docs.
If not configuring one is not desired for testing purposes we can choose to configure a dummy string.
Beta can also be declared for a full chapter or a whole site.
Chapter level it would be declared in the navigation YAML.
site: to be decided.
MDX supports importing mdx and react components as react components:
https://mdxjs.com/getting-started#documents
Somehow it currently does not work in our setup.
Ref: #85
From a usability perspective it's desired that the main nav does not change its scroll position when navigating to a different page in the same site (= microsite with same nav).
It requires some technical investigation into how GatsbyJS behaves when navigating concerning component state.
To be able to execute go-lives of new products and websites in a structured way it needs to be possible to configure the search indexing on a site-wide level and override it on a per-page level.
The site wide default should be configurable in the site's gatsby-config.js , per-page overrides should be MDX frontmatter (or use react helmet in pure JS pages)
Whether the implementation uses robots.txt
or the HTML meta attributes or a combination is open to implementation as long as overriding works in both directions (override a page to be visible in an otherwise excluded site, override a page to be hidden in an otherwise indexed site).
References:
See existing implementation (done in gatsby-ssr.js and excluding certain evironments)
example with commercetools ID:
import React from 'react';
import RootWrapper from './root-wrapper';
export const wrapRootElement = RootWrapper;
export function onRenderBody({ setPostBodyComponents }) {
if (process.env.NODE_ENV === 'production' && !process.cwd().endsWith('/test'))
setPostBodyComponents([
<script
key="pqr"
type="text/javascript"
src="https://cdn.cookielaw.org/langswitch/99bb6fae-765a-4fc5-9b6e-8c89a353335d.js"
charSet="UTF-8"
onLoad="function OptanonWrapper() {};"
/>
]);
}
Maybe we can detect preview builds using ZEIT variables: https://zeit.co/docs/v2/more/now-for-github/
Take advantage of design system, spaces and other tools from the root theme
./gradlew shadow
to generate jar file.rmf-codegen % time ./rmf-gen.sh generate -o <gatsby-theme-api-specs-path> -t ramldoc <raml-api-path>
Given that the bulk of intended users don't have software development background, the process can get easily complicated and therefore confusing. Setting up the actual doc site already has several steps.
Based on the RMF based file generator by @jenschude, let's expose the "RAML 1.0 Datatype" files on the GatsbyJS GraphQL API.
It can be implemented as an additional functionality in the transformer-raml branch that we started already.
js-yaml
or yaml
(annotationsInBrackets)
RamlDataType
node on GraphQL, the parent node being the file read from.what do you think?
If a site uses the theme but also uses other plugins and these plugins are creating graphQL surface, the generated scheme file is updated in the theme plugin source code without the theme actually being affected.
If that modified file is accidentally committed it contains scheme that has nothing to do with the theme.
overall impression: since the theme is not generating any graphQL surface itself by creating nodes I think it does not need to have any sort of persisted schema definition.
To be able to better understand how the internal navigational features of the website are actually used it's necessary to first instrument the respective links with Google Analytics Events.
Page navigation path analysis is built-in in GA and the GatsbyJS plugin takes care of tracking page changes (independently whether via react or as actual reloads).
But events need to be attached manually. The GatsbyJS google analytics plugin provides a wrapper function that allows robust event tracking.
Reading the relatively small source of the GA plugin explains most of what's going on:
https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-google-analytics/src/index.js
Outbound Links are also tracked as Events, but the code is blocking in that case and it has its own Action category and name.
GA docs here: https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#events
MainNav
, TopNav
, IndexNav
, SearchResults
etc. .click
(analogous to the actual event that happened in the DOM, but can be any string.Other hierarchies are possible, too (e.g. Category "Nav" , Type "Click", Label "Main -> Getting Started -> Setting Up your IDE")
It must be chosen carefully what to track and what not because spamming the event tracking does not help either.
A visual heatmap cannot be generated from this type of data, but tracking the navigation structure logically has other advantages (robust against responsive design differences and varying menu lengths, scolling position of the menu etc)
gatsby-theme-api-docs configures the legacy raml parser with our default standards, which is good. But one option should be configured on site level, that's the includeApis
whitelist.
default should be an empty or no id configured in a way that does not track but does not throw errors either.
The Docsearch UI shows the first three levels of the level configuration that was put into the docsearch github configs repo.
At the moment the first level is the Page title (= H1), the second is the H2 structure, the third is the H3 structure.
It has two issues:
If we want to stick to the UX idea of docsearch that it's a little like a filtered subset of the complete information hierarchy, I propose to move the usage of the hierarchy one level up:
You would not be able to do the kind of super-deep deeplink matches we currently have (e.g. searching for a specific update action or type name and jumping there but we could
Alternatively we could first try the feature that enables faceting by attributes. I.e. sticking with the current hierarchy that links deep into the details and allowing the user to filter the results to a part of the documentation.
In general I think the hierarchy in the results must be in sync with what a breadcrumb would be to help users build and retain a mental map of the site structure.
FYI @Shecki not urgent but a think you can take into your breadcrumb etc. considerations
apiKey
and indexName
. We can also choose to simply allow mixing any allowed docsearch config into a default config./
keyboard shortcut and taking over the current selection in a separate step. The docsearch widget has an own bindKeyboardShortcuts
setting but it's badly implemented and worked only on US keyboards the last time we tried.Keep in mind that this is the special free Algolia docsearch offering, not the Algolia product sold for money.
The generic Algolia has an own set of React components, but docsearch has a pre-built widget for the docsearch offering that has to be used on docsearch sites.
This is the Docsearch widget: https://github.com/algolia/docsearch
Here's how Facebook's docosaurus includes it in React.js: https://github.com/facebook/Docusaurus/blob/master/packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.js - not officially open source but you can take it as an inspiration.
This GatsbyJS documentation is therefore not applicable to this case: https://www.gatsbyjs.org/docs/adding-search-with-algolia/
@nkuehn what is your idea for licensing the packages here?
(absolute nice-to-have just for robustness)
Currently, if a site's content never uses a frontmatter key that is queried by our implementation, the site build fails because the queried field is not on the graphQL schema.
The "beta" frontmatter is such a case.
I don't know whether it is possible at all to change the graphQL surface of other plugins (gatsbyjs is shielding plugins from each other pretty good), so this might well simply not work.
To gain more independence of Netlify's analysis features it would help if the broken link checker would warn on unencrypted URLs. It's checking all source links of images, scripts etc, too so that's a relatively broad coverage.
For go-live we will only show the placeholder {region}
in the base URL part of API and other docs, but it's much more useful to have user specific state that holds their default region and the components rendering API hosts and MC urls dynamically pick that up.
Required: A design and a naming strategy for the browser storage.
There must not be a default region, default is showing a placeholder or selector
(updated, doesn't have to be an NPM package)
gatsby-starter-commercetools-docs
Not doing:
resources:
Should take advantage of design system, spacings and other tools from the root theme.
Technical Writing works a lot with a concept named "Topic Based Writing" which is a fancy name for re-using content across many places. MDX has native support for transclusion and being able to use it would make this a much more interesting tool for large-scale usage.
MDX documentation: https://mdxjs.com/getting-started#documents
If done it would be very likely that the centralized content lives in a separate package.
example usage
import TopicBasedWritingConcept from "../topics/concepts/topic-based-writing.mdx"
<TopicBasedWritingConcept />
It did not work out of the box.
In MDX / MD authors are allowed to write HTML definition lists. should have spacing and indentation as designed for the "Subscription Heath Status" example content.
Types that are defined on a page somewhere on the website should be linked. This affect various property types and response representations on the Import API site.
Expectation
Types links are queried from graphql nodes generated gatsby-transformer-mdx-introspection tool, so the links are expected to be available in graphql.
In the current case the links are not present in graphql. So types are rendered as a string.
The next step is to look into the gatsby-transformer-mdx-introspection to implement the fix.
Create new api test website that is based on the new api theme. Should contain eventual (empty) pages and their navigations
gatsby-transformer-raml should be configurable with the following options:
{
includeApis: ['import', 'import-storage-api', 'test'],
movePropertiesToTop: [
'id',
'version',
'key',
'createdAt',
'createdBy',
'lastModifiedAt',
'lastModifiedBy',
],
movePropertiesToBottom: ['custom'],
},
The current SVG orginal of the site icon is not square, which the manfest plugin complains about for good reason. The resulting icons have the right part of the CT cube cut off.
Let's get a properly shaped SVG and ask a design wizard to create readily rendered variants for the very small resolutions (16x, 32x) that have smooth lines.
n/t
I just took a look at home and found the positioning of the main content scrollbar less than ideal. It feels visually buggy to have it not at the right edge of the viewport and it overlaps the index nav content.
this shot is taken in Firefox on windows 10, but also in Chrome on Windows 10. Maybe "emulatable" on a Mac, too on an external Monitor with a conventional mouse attached.
@Shecki can you make your opinion?
update: here's a branch with experiments in an actual MDX file: https://github.com/commercetools/commercetools-docs-kit/blob/extended-code-syntax-brainstorming/websites/docs-smoke-test/src/content/code-samples/multi-language-code.mdx
Alternatively to writing example code in markdown as fenced code blocks an author must be able to store the example code in a separate standalone file and pull it into any MDX page. This provides the advantage that the code examples can be own fully valid software projects that are automatically tested.
This issue covers the case of a single-language example like fenced code blocks.
We decided to leverage MDX import statements and custom webpack loaders, which is how gatsbyJS is generally built internally, too. Webpack can be configured cleanly by a plugin like the theme (see reference link below)
Any import statement loading from a path containing /code-examples/
(plus maybe further restrictions like whitelisting packages if possible) is managed by a custom loader that returns a function component that is wrapping our standard Code component. It's detecting the language by file name and injects the content.
The following code is pseudo-MDX
import CartCreateExampleJs from '@commercetools-docs/code-examples/javascript/cart/create.js'
import CartCreateExampleJava from '../../code-examples/java/cart/create.java'
<CartCreateExampleJs title="Creating a Cart in Javascript" />
<CartCreateExampleJava highlightLines="5-10" title="Creating a Cart in Java" />
We don't need to support cases that cannot be derived from the file name extension (e.g. individual terminal cli commands that are not part of a shell script)
As the list of design tokens keeps growing, the current token names (especially for colors) are not super useful anymore.
I'd like to go over them (when I have some time) and provide more meaningful names.
Example of "good" names:
commercetools-docs-kit/packages/ui-kit/src/design-system.js
Lines 58 to 68 in d62f3b5
To make the way content is written easier to refactor (i.e. rename or move around in the content hierarchy) it would be helpful to allow authors to make import statements absolute.
e.g. when including an image or other MDX or code example file, instead of
import OptimisticConcurrencyDefinition from "../../topics/definitions/optimistic-concurrency.mdx"
writing
import OptimisticConcurrencyDefinition from "topics/definitions/optimistic-concurrency.mdx"
would yield less problem when e.g. moving the file that includes the content.
Root should be the src
directory of the current package.
Gatsby supports this explicitly but it has to be configured:
https://www.gatsbyjs.org/docs/add-custom-webpack-config/#absolute-imports
Pseudo-spec:
In any case, the html "title" attribute does not have to be set if
& are properly used.If a whole microsite is configured to be excluded from search engines, its content will not be indexed in the on-site search, too.
To avoid user confusion, such sites should not have the on-site search box because such a box suggests that the topic area you are currently reading is indexed.
Independently, we can consider configuring whether a top menu is shown or not. In total, it's about a "Private Beta" mode that has the following effects:
I noticed that in the production build some styles are "duplicated" all over the page, for example for links.
This seems to be a "known behavior" in Emotion: emotion-js/emotion#1061
We should investigate how to reduce the duplication. They mention having a "common" emotion ancestor, but I'm not sure exactly what that means.
update: here's a branch with experiments in an actual MDX file: https://github.com/commercetools/commercetools-docs-kit/blob/extended-code-syntax-brainstorming/websites/docs-smoke-test/src/content/code-samples/multi-language-code.mdx
(This builds on top of #64 )
Since markdown does not allow to express multi-language code blocks examples that have a language switcher need to be pulled from external files. The implementation may also support multi-language code blocks that hold the actual code in the markdown document, but that is not the design we optimize for.
pseudo-MDX based on the pattern developed for single language code in #64 :
<MultiCode title="Creating a Cart">
<CartCreateExampleJs />
<CartCreateExampleJs highlightLines="5-10" />
</MultiCode>
This tickets stands for the first iteration, which must not yet support a data layout that has all the languages next to each other in a folder and allows to pull all languages via a wildcard import.
The languages end up in the dropdown on the right of the title.
It must be possible to pass a title
Child Elements are always single code examples that are rendered without their title bar and copy button.
To be able to consistently format we want to suggest / request an improvement to the gatsby images plugin that allows to configure that it always wraps the images in a <figure>
tag independently of whether there will be a <figcaption>
. this allows for more consistent styling across the two use cases.
The current master has a flash of unstyled content (tested on a windows 10 machine in Firefox and Chrome).
The vertical spacing both in the left hand nav and the body content is initially higher and gets reduced after page load.
The main container y overflow is not set to auto, so when on windows or having a mouse attached the scrollbar is visible independently of whether it's needed.
From a windows user perspective that's perceived as a bug because it deviates from the 99% convention how websites behave.
The advantage of the path prefix is
CON: one might want to change the one but not the other later on, but do we want to encourage the names and path to be different?
A theme that extends @commercetools-docs/gatsby-theme-docs. The new name gatsby-theme-api-docs
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.