Skip to content

Commit dd0d741

Browse files
abrulicabrulic
authored
docs for docs-template and small improvements (#13)
1 parent 77ac630 commit dd0d741

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+1640
-1444
lines changed

‎.github/workflows/build-documentation.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,25 @@ jobs:
3131
- name: Generate docs
3232
working-directory: docs
3333
run: pnpm run generate:docs
34+
35+
36+
deploy:
37+
name: 🚀 Deploy Release
38+
needs: [build-docs]
39+
runs-on: ubuntu-latest
40+
steps:
41+
- uses: actions/checkout@v4
42+
43+
- uses: forge-42/fly-deploy@v1.0.0-rc.2
44+
id: deploy
45+
env:
46+
FLY_ORG: ${{ vars.FLY_ORG }}
47+
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
48+
FLY_REGION: ${{ vars.FLY_REGION }}
49+
with:
50+
app_name: ${{github.event.repository.name}}-${{ github.ref_name }}
51+
env_vars: |
52+
APP_ENV=production
53+
GITHUB_OWNER=${{ github.repository_owner }}
54+
GITHUB_REPO=${{ github.event.repository.name }}
55+
GITHUB_REPO_URL=https://github.com/${{ github.repository }}

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ This template is designed to support a flexible content structure using `.md` an
44

55
The project is built using the [@forge-42/base-stack](https://github.com/forge-42/base-stack) and leverages the [content-collections](https://github.com/sdorra/content-collections).
66

7+
> **Note**:
8+
> We added a few `FIXME` comments in the codebase as notes to you. These simply mark small places where we expect you to make changes. Nothing major — it should only take you 2 minutes to go through them.
9+
710

811
## Documentation Template Structure Overview
912

‎app/components/code-block/code-block-elements.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ export const PreElement = ({ lines, className = "", ...props }: PreElementProps)
5757
<pre
5858
{...props}
5959
className={cn(
60-
"relative overflow-x-auto rounded-lg border border-[var(--color-border)] bg-[var(--color-code-block-bg)] py-4 font-mono text-[var(--color-code-block-text)] text-xs leading-relaxed sm:text-sm md:text-base",
60+
"scrollbar scrollbar-thin relative overflow-x-auto rounded-lg border border-[var(--color-border)] bg-[var(--color-code-block-bg)] py-4 font-mono text-[var(--color-code-block-text)] text-xs leading-relaxed sm:text-sm md:text-base [&::-webkit-scrollbar-thumb:hover]:cursor-pointer",
6161
className
6262
)}
6363
>

‎app/components/code-block/code-block-syntax-highlighter.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ const MASTER_REGEX = new RegExp(
1313
"//.*?(?=\\n|$)",
1414
// multi-line comment
1515
"/\\*[\\s\\S]*?\\*/",
16+
// hash comment at start of line
17+
"^\\s*#.*$",
1618
// strings
1719
"(['\"])(?:(?!\\1)[^\\\\]|\\\\.)*\\1",
1820
// numbers
@@ -101,7 +103,7 @@ const isKeyword = (value: string) => KEYWORDS.includes(value)
101103
const isOperator = (value: string) => OPERATORS.includes(value)
102104
const isFunction = (value: string) => /^[A-Z]/.test(value)
103105
const isWhitespace = (value: string) => /^\s/.test(value)
104-
const isComment = (value: string) => value.startsWith("//") || value.startsWith("/*")
106+
const isComment = (v: string) => v.startsWith("//") || v.startsWith("/*") || /^\s*#/.test(v)
105107
const isString = (value: string) => /^['"`]/.test(value)
106108
const isNumber = (value: string) => /^\d/.test(value)
107109
const isIdentifier = (value: string) => /^[a-zA-Z_$]/.test(value)

‎app/components/code-block/code-block.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ export const CodeBlock = ({ children, className = "", ...props }: CodeBlockProps
1212
const lines = processLines(code)
1313

1414
return (
15-
<div className="group relative">
15+
<div className="group relative ">
1616
<PreElement lines={lines} className={className} {...props} />
1717
<CopyButton lines={lines} />
1818
</div>

‎app/components/logo.tsx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,14 @@
11
import type { ReactNode } from "react"
2+
import { href, useNavigate } from "react-router"
23

34
export const Logo = ({ children }: { children: ReactNode }) => {
5+
const navigate = useNavigate()
46
return (
5-
<div className="relative block font-semibold font-space text-[var(--color-text-active)] text-lg md:text-2xl xl:text-3xl">
7+
// biome-ignore lint/a11y/useKeyWithClickEvents: we don't need keyboard access for this
8+
<div
9+
onClick={() => navigate(href("/:version?/home"))}
10+
className="relative block font-semibold font-space text-[var(--color-text-active)] text-lg md:text-2xl xl:text-3xl"
11+
>
612
{children}
713
</div>
814
)

‎app/components/page-mdx-article.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { MDXWrapper } from "./mdx-wrapper"
44

55
export default function PageMdxArticle({ page }: { page: Page }) {
66
return (
7-
<article className="prose prose-invert w-full min-w-0 max-w-4xl flex-grow px-3 py-3 prose-headings:text-[var(--color-text-active)] prose-p:text-[var(--color-text-active)] text-sm leading-6 sm:text-base md:px-6 md:py-4 md:text-lg">
7+
<article className="prose prose-invert w-full min-w-0 max-w-4xl flex-grow px-3 py-3 prose-headings:text-[var(--color-text-active)] prose-p:text-[var(--color-text-active)] text-sm leading-6 sm:text-base md:px-6 md:py-4 md:text-lg xl:leading-8">
88
<header className=" border-[var(--color-border)] border-b">
99
<Title className="mt-0 font-bold text-[var(--color-text-heading)]" as="h1">
1010
{page.title}

‎app/components/table-of-content.tsx‎

Lines changed: 46 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { useCallback } from "react"
1+
import { useCallback, useEffect, useRef } from "react"
22
import { Link, useLocation, useNavigate } from "react-router"
33
import { useActiveHeadingId } from "~/hooks/use-active-heading-id"
44
import type { HeadingItem } from "~/utils/extract-heading-tree-from-mdx"
@@ -48,10 +48,11 @@ const TocItem = ({ item, depth = 0, activeId, onItemClick }: TocItemProps) => {
4848
<div>
4949
<Link
5050
to={`#${item.slug}`}
51-
style={{ paddingLeft }}
5251
className={className}
5352
onClick={handleClick}
5453
aria-current={isActive && "location"}
54+
data-toc-slug={item.slug}
55+
style={{ paddingLeft, scrollMarginTop: 8 }}
5556
>
5657
{item.title}
5758
</Link>
@@ -66,12 +67,6 @@ const TocItem = ({ item, depth = 0, activeId, onItemClick }: TocItemProps) => {
6667
)
6768
}
6869

69-
const TableOfContentsHeader = () => (
70-
<h2 className="mb-4 border-[var(--color-border)] border-b pb-2 font-semibold text-[var(--color-text-active)] text-base">
71-
On this page
72-
</h2>
73-
)
74-
7570
const Navigation = ({
7671
items,
7772
activeId,
@@ -80,14 +75,49 @@ const Navigation = ({
8075
items: HeadingItem[]
8176
activeId: string | null
8277
onItemClick: (slug: string) => Promise<void>
83-
}) => (
84-
<nav aria-label="Table of contents" className="-mr-4 max-h-[calc(100vh-var(--header-height))] overflow-y-auto pr-4">
85-
<div className="space-y-1 pb-2">
86-
{items.map((item) => (
87-
<TocItem key={item.slug} item={item} activeId={activeId} onItemClick={onItemClick} />
88-
))}
89-
</div>
90-
</nav>
78+
}) => {
79+
const navRef = useRef<HTMLDivElement>(null)
80+
81+
useEffect(() => {
82+
if (!activeId) return
83+
const nav = navRef.current
84+
if (!nav) return
85+
86+
const el = nav.querySelector<HTMLElement>(`[data-toc-slug="${CSS.escape(activeId)}"]`)
87+
if (!el) return
88+
89+
const padding = 24
90+
const elTop = el.offsetTop
91+
const elBottom = elTop + el.offsetHeight
92+
const viewTop = nav.scrollTop
93+
const viewBottom = viewTop + nav.clientHeight
94+
95+
if (elTop < viewTop + padding) {
96+
nav.scrollTo({ top: Math.max(elTop - padding, 0), behavior: "smooth" })
97+
} else if (elBottom > viewBottom - padding) {
98+
nav.scrollTo({ top: elBottom - nav.clientHeight + padding, behavior: "smooth" })
99+
}
100+
}, [activeId])
101+
102+
return (
103+
<nav
104+
ref={navRef}
105+
aria-label="Table of contents"
106+
className="-mr-4 max-h[calc(100vh-var(--header-height))] overflow-y-auto pr-4"
107+
>
108+
<div className="space-y-1 pb-2">
109+
{items.map((item) => (
110+
<TocItem key={item.slug} item={item} activeId={activeId} onItemClick={onItemClick} />
111+
))}
112+
</div>
113+
</nav>
114+
)
115+
}
116+
117+
const TableOfContentsHeader = () => (
118+
<h2 className="mb-4 border-[var(--color-border)] border-b pb-2 font-semibold text-[var(--color-text-active)] text-base">
119+
On this page
120+
</h2>
91121
)
92122

93123
export const TableOfContents = ({ items }: TableOfContentsProps) => {

‎app/routes/documentation-homepage.tsx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ export const meta = ({ data }: Route.MetaArgs) => {
1313
return generateMetaFields({
1414
domain,
1515
path: `/${version}/home`,
16-
title: `${title} · Package Name`,
16+
// FIXME Change "Docs Template" to your package name
17+
title: `${title} · Docs Template`,
1718
description,
1819
})
1920
}

‎app/routes/documentation-layout.tsx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ export default function DocumentationLayout({ loaderData }: Route.ComponentProps
2424
<Header>
2525
<div className="flex items-start gap-3">
2626
<Logo>
27-
{/* Replace with your Logo */}
28-
<span className="p-0">REACT ROUTER DEVTOOLS</span>
27+
{/* FIXME Replace with your Logo */}
28+
<span className="p-0">DOCS-TEMPLATE</span>
2929
</Logo>
3030
</div>
3131
<div className="inline-flex items-center gap-2 xl:gap-3">
@@ -42,7 +42,7 @@ export default function DocumentationLayout({ loaderData }: Route.ComponentProps
4242
<Outlet />
4343
</main>
4444
</div>
45-
{/* You can add custom footer component here */}
45+
{/* FIXME You can add custom footer component here */}
4646
</div>
4747
)
4848
}

0 commit comments

Comments
 (0)