Merge pull request #11510 from backstage/techdocs/do-not-transform-headings

[TechDocs] Fix headings transformations

.changeset/strong-lies-explain.md

@@ -0,0 +1,5 @@
+---
+'@backstage/theme': patch
+---
+
+Adds optional `htmlFontSize` property and also sets typography design tokens for h5 and h6 in base theme.

.changeset/techdocs-eyes-sit.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs-backend': patch
+---
+
+Add sample headings on the documented component homepage.

.changeset/techdocs-sheep-talk.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs': patch
+---
+
+Remove the 60% factor from the font size calculation of headers to use the exact size defined in BackstageTheme.

packages/theme/api-report.md

@@ -145,5 +145,6 @@ export type SimpleThemeOptions = {
   defaultPageTheme: string;
   pageTheme?: Record<string, PageTheme>;
   fontFamily?: string;
+  htmlFontSize?: number;
 };
 ```

packages/theme/src/baseTheme.ts

@@ -24,6 +24,7 @@ import {
 } from './types';
 import { pageTheme as defaultPageThemes } from './pageTheme';
 
+const DEFAULT_HTML_FONT_SIZE = 16;
 const DEFAULT_FONT_FAMILY =
   '"Helvetica Neue", Helvetica, Roboto, Arial, sans-serif';
 
@@ -37,6 +38,7 @@ export function createThemeOptions(
 ): BackstageThemeOptions {
   const {
     palette,
+    htmlFontSize = DEFAULT_HTML_FONT_SIZE,
     fontFamily = DEFAULT_FONT_FAMILY,
     defaultPageTheme,
     pageTheme = defaultPageThemes,
@@ -57,9 +59,17 @@ export function createThemeOptions(
       },
     },
     typography: {
+      htmlFontSize,
       fontFamily,
+      h6: {
+        fontWeight: 700,
+        fontSize: 20,
+        marginBottom: 2,
+      },
       h5: {
         fontWeight: 700,
+        fontSize: 24,
+        marginBottom: 4,
       },
       h4: {
         fontWeight: 700,

packages/theme/src/types.ts

@@ -149,6 +149,7 @@ export type SimpleThemeOptions = {
   defaultPageTheme: string;
   pageTheme?: Record<string, PageTheme>;
   fontFamily?: string;
+  htmlFontSize?: number;
 };
 
 /**

plugins/techdocs-backend/examples/documented-component/docs/index.md

@@ -11,6 +11,20 @@ You can see also:
 
 ## Basic Markdown
 
+Headings:
+
+# h1
+
+## h2
+
+### h3
+
+#### h4
+
+##### h5
+
+###### h6
+
 Here is a bulleted list:
 
 - Item one

plugins/techdocs/src/reader/transformers/styles/rules/typeset.ts

@@ -16,8 +16,14 @@
 
 import { RuleOptions } from './types';
 
+type RuleTypography = RuleOptions['theme']['typography'];
+
+type BackstageTypography = RuleTypography & {
+  htmlFontSize?: number;
+};
+
 type TypographyHeadings = Pick<
-  RuleOptions['theme']['typography'],
+  RuleTypography,
   'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
 >;
 
@@ -33,13 +39,15 @@ export default ({ theme }: RuleOptions) => `
 }
 
 ${headings.reduce<string>((style, heading) => {
+  const htmlFontSize =
+    (theme.typography as BackstageTypography).htmlFontSize ?? 16;
   const styles = theme.typography[heading];
   const { lineHeight, fontFamily, fontWeight, fontSize } = styles;
   const calculate = (value: typeof fontSize) => {
     let factor: number | string = 1;
     if (typeof value === 'number') {
-      // 60% of the size defined because it is too big
-      factor = (value / 16) * 0.6;
+      // convert px to rem
+      factor = value / htmlFontSize;
     }
     if (typeof value === 'string') {
       factor = value.replace('rem', '');