proposal: new docs customization options #582
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
3 Ignored Deployments
|
|
🌿 Preview your docs: https://fern-preview-3ff486aa-27ea-44cd-bf44-52b70a1abde8.docs.buildwithfern.com |
PR PreviewBuilding... |
| @@ -0,0 +1,90 @@ | |||
| # yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json | |||
There was a problem hiding this comment.
All of the types that are shared between read and write are centralized in common .yml files. This makes it a lot easier to understand the impact a change has between read and write, and compare why they are different in some small cases.
| ThemeConfigRead: | ||
| extends: ThemeConfigShared | ||
| properties: | ||
| background: BackgroundSolidOrGradient |
There was a problem hiding this comment.
For example, this transformation should never have happened!
| accentPrimary: optional<ColorConfig> | ||
| background: optional<ColorConfig> | ||
|
|
||
| ColorsConfigV3: |
There was a problem hiding this comment.
We'll need to introduce a v4 of this config where:
ColorsConfigV4:
properties:
dark: optional<ThemeConfigRead>
light: optional<ThemeConfigRead>Alternatively, we can just make all of the properties dark or light:
ColorsConfigV4:
properties:
logo: optional<commons.ThemedFileId>
accentPrimary: optional<ThemedRgbaColor>
backgroundColor: optional<ThemedBackgroundColor>
# ...I haven't decided which one is easier to implement from; so we'll leave this decision to a future PR.
| fernButton: ./fern-button.yml | ||
|
|
||
| types: | ||
| HeaderLinksConfig: |
There was a problem hiding this comment.
Instead of navbarLinks: optional<list<NavbarLinks>>, we'll
- call this "header links" because they are links rendered in the header
- leave this as an object to allow for future configuration options
- use the
FernLinkButtonConfigfor full button customizability.
| custom: CustomFontConfig | ||
| google: GoogleFontConfig | ||
|
|
||
| GoogleFontConfig: |
There was a problem hiding this comment.
GoogleFontConfig is new here. This is how we'd implement it: vercel/next.js#40345
| id: optional<rootCommons.DocsConfigId> | ||
| config: DocsConfig | ||
| search: SearchInfo | ||
|
|
||
| # deprecated |
There was a problem hiding this comment.
we should eventually remove this from read.
| - HeaderPositionDeprecated | ||
|
|
||
| SidebarOrHeaderPlacementDeprecated: | ||
| enum: |
There was a problem hiding this comment.
This was the best way to express that we want to rename HEADER to header because the conversions is confusing.
the following two methods did not work:
SidebarOrHeaderPlacementWrite:
extends: SidebarOrHeaderPlacement
enum:
- HEADER
- SIDEBARbecause extends is not supported in enums
SidebarOrHeaderPlacementWrite:
enum:
- header
- sidebar
- HEADER
- SIDEBARbecause sidebar and SIDEBAR collide in generated types. (this was caught in fern generate, and not in fern check)
Also, I would have expected this to work, but it doesn't:
- type: VERSION
availability: deprecated
| # yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json | ||
|
|
||
| types: | ||
| FernLinkButtonConfig: |
There was a problem hiding this comment.
This is how expressive our config should be when it comes to UI elements.
Eventually we want to be able to construct a layout-rich page using YML
layout:
theme: homepage
heading: test.yml
image: assets/image.png
sections:
- markdown: |
### inline markdown content
- markdown: sections/markdown-file.yml
- buttons:
- buttonA
- text: An inline button
icon: puzzle
components:
buttonA:
text: My button
icon: home
href: https://google.com
abvthecity
changed the title
abvthecity
changed the title
PR PreviewBuilding... |
|
🌿 Preview your docs: https://fern-preview-e6c1b28e-4902-4bdf-81e9-24c73de403dc.docs.buildwithfern.com |
No description provided.