@brillout/docpress 0.5.39 → 0.5.40-commit-51be4fa

package/{dist/components → components}/features/FeatureList.css

@@ -1,4 +1,3 @@
-/* src/components/features/FeatureList.css */
 @media screen and (min-width: 840px) {
   .features-row {
     display: grid;
@@ -17,6 +16,7 @@
     grid-column: 1 / 3;
   }
 }
+
 @media screen and (min-width: 840px) {
   .features-row.single-column .feature {
     grid-column: 1 / span 2 !important;
@@ -25,11 +25,13 @@
     margin: auto !important;
   }
 }
+
 #features {
   margin: auto;
   margin-top: 0;
   max-width: 1080px;
 }
+
 #features summary p {
   margin: 10px 0;
 }
@@ -44,6 +46,7 @@
 .learn-more h3:first-of-type {
   margin-top: 15px;
 }
+
 .learn-more {
   border: var(--border-width) solid var(--border-color);
   padding: 10px 8px;
@@ -95,6 +98,8 @@ aside.learn-more.right-side {
   border-bottom: 0 !important;
   z-index: 1;
 }
+
+/* Hide top border of .learn-more */
 .learn-more {
   position: relative;
   top: calc(-1 * var(--border-width));
@@ -103,8 +108,11 @@ aside.learn-more.right-side {
   position: relative;
   z-index: 1;
 }
+
 .feature .chevron {
-  transition: filter 0.3s ease-in-out, transform 0.3s ease-in-out !important;
+  transition:
+    filter 0.3s ease-in-out,
+    transform 0.3s ease-in-out !important;
 }
 .feature.selected .chevron {
   transform: rotate(180deg);

package/components/features/FeatureList.tsx

@@ -0,0 +1,114 @@
+import React from 'react'
+import './FeatureList.css'
+import iconChevron from './chevron.svg'
+
+export { FeatureList }
+
+type FeatureProps = {
+  title: React.ReactNode
+  desc: React.ReactNode
+  learnMore?: React.ReactNode
+  isSecondaryFeature?: true
+}
+
+function FeatureList({ features }: { features: FeatureProps[] }) {
+  const numberOfFeatures = features.length
+  const numberOfRows = Math.ceil(numberOfFeatures / 2)
+  return (
+    <div id="features">
+      {Array.from({ length: numberOfRows }, (_, i) => {
+        const feature1Id = 2 * i + 0
+        const feature2Id = 2 * i + 1
+        const feature1 = features[feature1Id]
+        const feature2 = features[feature2Id]
+        const className = ['features-row', feature2 ? '' : 'single-column'].filter(Boolean).join(' ')
+        return (
+          <div className={className} key={i}>
+            <Feature {...{ ...feature1, featureId: feature1Id }} />
+            {feature2 && <Feature {...{ ...feature2, featureId: feature2Id }} />}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+function Feature({ title, desc, learnMore, isSecondaryFeature, featureId }: FeatureProps & { featureId: number }) {
+  const name = `feature-${featureId}`
+  const rightSide = featureId % 2 === 1
+  return (
+    <>
+      <FeatureHead name={name} hasLearnMore={!!learnMore} isSecondaryFeature={isSecondaryFeature}>
+        {' '}
+        <h2>{title}</h2>
+        {desc}
+      </FeatureHead>
+      {!!learnMore && (
+        <LearnMore name={name} rightSide={rightSide}>
+          {learnMore}
+        </LearnMore>
+      )}
+    </>
+  )
+}
+
+function FeatureHead({
+  children,
+  name,
+  hasLearnMore,
+  isSecondaryFeature,
+  className = ''
+}: {
+  className?: string
+  name?: string
+  hasLearnMore?: boolean
+  isSecondaryFeature?: true
+  children: React.ReactNode
+}) {
+  return (
+    <summary
+      className={[
+        className,
+        'feature',
+        'colorize-on-hover',
+        hasLearnMore && 'has-learn-more',
+        isSecondaryFeature && 'secondary-feature'
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      id={name && `feature-${name}`}
+      style={{ cursor: (hasLearnMore && 'pointer') || undefined }}
+    >
+      {children}
+      {hasLearnMore && (
+        <div style={{ textAlign: 'center', marginTop: '1em' }}>
+          <button
+            type="button"
+            style={{
+              textAlign: 'center',
+              padding: '0 7px',
+              paddingTop: 3,
+              paddingBottom: 1,
+              display: 'inline-block',
+              fontSize: '10px',
+              textTransform: 'uppercase',
+              letterSpacing: '1px',
+              fontWeight: 600
+            }}
+          >
+            <span className="decolorize-5">Learn more</span>
+            <br />
+            <img className="decolorize-4 chevron" src={iconChevron} height="7" style={{ marginTop: 2 }} />
+          </button>
+        </div>
+      )}
+    </summary>
+  )
+}
+function LearnMore({ children, name, rightSide }: { name: string; children: React.ReactNode; rightSide: boolean }) {
+  return (
+    <aside className={'learn-more ' + (rightSide ? 'right-side' : '')} id={`learn-more-${name}`}>
+      {children}
+    </aside>
+  )
+}

package/components/features/initFeatureList.ts

@@ -0,0 +1,66 @@
+import { assert } from '../../utils/client'
+
+addTwitterWidgets()
+addFeatureClickHandlers()
+window.__docpress_hydrationFinished = true
+
+function addTwitterWidgets() {
+  loadScript('https://platform.twitter.com/widgets.js')
+}
+
+function addFeatureClickHandlers() {
+  const featureEls: HTMLElement[] = Array.from(
+    document.getElementById('features')!.querySelectorAll('.feature.has-learn-more')
+  )
+  featureEls.forEach((featureEl) => {
+    featureEl.onclick = () => {
+      expandLearnMore(featureEl)
+    }
+  })
+}
+
+function expandLearnMore(featureEl: HTMLElement) {
+  const featureId = featureEl.id
+  assert(featureId.startsWith('feature-'), { featureId })
+  const featureName = featureId.slice('feature-'.length)
+
+  const selectedClass = 'selected'
+  const learnId = 'learn-more-' + featureName
+  const learnEl = document.getElementById(learnId)
+  assert(learnEl, { learnId })
+
+  const isExpanded = featureEl.classList.contains(selectedClass)
+
+  if (!isExpanded) {
+    const rowEl = featureEl.parentNode as HTMLElement
+    if (getComputedStyle(rowEl, 'display') === 'grid') {
+      ;[
+        ...(rowEl.querySelectorAll('.learn-more') as any as HTMLElement[]),
+        ...(rowEl.querySelectorAll('.feature') as any as HTMLElement[])
+      ].forEach((el) => {
+        el.classList.remove(selectedClass)
+      })
+    }
+  }
+
+  ;[featureEl, learnEl].forEach((el) => {
+    el.classList.toggle(selectedClass)
+  })
+}
+
+function loadScript(scriptUrl: string): void {
+  assert(scriptUrl.startsWith('https://'))
+  const scriptEl = document.createElement('script')
+  scriptEl.src = scriptUrl
+  scriptEl.async = true
+  scriptEl.setAttribute('charset', 'utf-8')
+  document.getElementsByTagName('head')[0].appendChild(scriptEl)
+}
+
+function getComputedStyle(el: HTMLElement, styleProp: string) {
+  return window.document.defaultView!.getComputedStyle(el).getPropertyValue(styleProp)
+}
+
+declare global {
+  var __docpress_hydrationFinished: undefined | true
+}

package/components/index.ts

@@ -0,0 +1,15 @@
+export * from '../utils/Emoji'
+export * from './Link'
+export * from './RepoLink'
+export * from './P'
+export * from './ReadingRecommendation'
+export * from './Note'
+export * from './ImportMeta'
+export * from './features/FeatureList'
+export * from './HorizontalLine'
+export * from './Supporters'
+export * from './Sponsors'
+export * from './Contributors'
+export * from './Consulting'
+export * from './CodeBlockTransformer'
+export * from './Comment'

package/config/getConfig.ts

@@ -0,0 +1,18 @@
+export { getConfig }
+import { assert, assertUsage } from '../utils/server'
+import { Config } from '../types/Config'
+
+function getConfig(): Config {
+  // We use `@ts-ignore` because the DocPress user most likely didn't add `vite/client` in his `tsconfig.json`.
+  // @ts-ignore
+  const globResult = import.meta.glob('/**/docpress.config.*([a-zA-Z0-9])', { eager: true })
+  const files = Object.keys(globResult)
+  assertUsage(files.length >= 1, 'No DocPress config file found `docpress.config.(js|ts|tsx|...)`')
+  assertUsage(
+    files.length === 1,
+    `Found multiple \`docpress.config.js\` files: ${files.map((f) => `\`${f}\``).join(', ')}. Define only one instead.`
+  )
+  const config = (Object.values(globResult)[0] as any).default as Config
+  assert(config)
+  return config
+}

package/config/resolvePageContext.ts

@@ -0,0 +1,186 @@
+import { assert, jsxToTextContent, objectAssign } from '../utils/server'
+import type { Heading, HeadingDetached } from '../types/Heading'
+import type { PageContextBuiltInServer } from 'vike/types'
+import type { MarkdownHeading } from '../markdownHeadingsVitePlugin'
+import type { Config } from '../types/Config'
+import { getConfig } from './getConfig'
+import { getHeadingsWithProcessedTitle, parseTitle } from '../parseTitle'
+
+export { resolvePageContext }
+export type { PageContextOriginal }
+export type { PageContextResolved }
+export type { Heading }
+
+type ReactComponent = () => JSX.Element
+type Exports = {
+  headings?: MarkdownHeading[]
+}
+type PageContextOriginal = PageContextBuiltInServer & {
+  Page: ReactComponent
+  exports: Exports
+}
+type PageContextResolved = ReturnType<typeof resolvePageContext>
+
+function resolvePageContext(pageContext: PageContextOriginal) {
+  const config = getConfig()
+  const processed = getHeadingsWithProcessedTitle(config)
+  const { headingsDetachedProcessed } = processed
+  let { headingsProcessed } = processed
+  const { activeHeading, activeNavigationHeading } = findHeading(
+    headingsProcessed,
+    headingsDetachedProcessed,
+    pageContext
+  )
+  let headingsOfDetachedPage: null | (Heading | HeadingDetached)[] = null
+  let headingsAll = [...headingsProcessed, ...headingsDetachedProcessed]
+  headingsAll = getHeadingsAll(headingsAll, pageContext, activeHeading)
+  if (activeNavigationHeading) {
+    headingsProcessed = getHeadingsAll(headingsProcessed, pageContext, activeNavigationHeading)
+  } else {
+    headingsOfDetachedPage = [activeHeading, ...getHeadingsOfTheCurrentPage(pageContext, activeHeading)]
+  }
+  const { title, isLandingPage, pageTitle } = getMetaData(
+    headingsDetachedProcessed,
+    activeNavigationHeading,
+    pageContext,
+    config
+  )
+  const { faviconUrl, algolia, tagline, twitterHandle, bannerUrl, websiteUrl } = config
+  const pageContextResolved = {}
+  objectAssign(pageContextResolved, {
+    ...pageContext,
+    meta: {
+      title,
+      faviconUrl,
+      twitterHandle,
+      bannerUrl,
+      websiteUrl,
+      tagline,
+      algolia
+    },
+    activeHeading,
+    headingsAll,
+    headingsProcessed,
+    headingsDetachedProcessed,
+    headingsOfDetachedPage,
+    isLandingPage,
+    pageTitle,
+    config
+  })
+  return pageContextResolved
+}
+
+function getMetaData(
+  headingsDetachedProcessed: HeadingDetached[],
+  activeNavigationHeading: Heading | null,
+  pageContext: { urlOriginal: string; exports: Exports },
+  config: Config
+) {
+  const url = pageContext.urlOriginal
+
+  let title: string
+  let pageTitle: string | JSX.Element | null
+  if (activeNavigationHeading) {
+    title = activeNavigationHeading.titleDocument || jsxToTextContent(activeNavigationHeading.title)
+    pageTitle = activeNavigationHeading.title
+  } else {
+    pageTitle = headingsDetachedProcessed.find((h) => h.url === url)!.title
+    title = jsxToTextContent(pageTitle)
+  }
+
+  const isLandingPage = url === '/'
+  if (!isLandingPage) {
+    title += ' | ' + config.projectInfo.projectName
+  }
+
+  if (isLandingPage) {
+    pageTitle = null
+  }
+
+  return { title, isLandingPage, pageTitle }
+}
+
+function findHeading(
+  headingsProcessed: Heading[],
+  headingsDetachedProcessed: HeadingDetached[],
+  pageContext: { urlOriginal: string; exports: Exports }
+): { activeHeading: Heading | HeadingDetached; activeNavigationHeading: Heading | null } {
+  let activeNavigationHeading: Heading | null = null
+  let activeHeading: Heading | HeadingDetached | null = null
+  assert(pageContext.urlOriginal)
+  const pageUrl = pageContext.urlOriginal
+  headingsProcessed.forEach((heading) => {
+    if (heading.url === pageUrl) {
+      activeNavigationHeading = heading
+      activeHeading = heading
+      assert(heading.level === 2, { pageUrl, heading })
+    }
+  })
+  if (!activeHeading) {
+    activeHeading = headingsDetachedProcessed.find(({ url }) => pageUrl === url) ?? null
+  }
+  if (!activeHeading) {
+    throw new Error(
+      [
+        `Heading not found for URL '${pageUrl}'`,
+        'Heading is defined for following URLs:',
+        ...headingsProcessed
+          .map((h) => `  ${h.url}`)
+          .filter(Boolean)
+          .sort()
+      ].join('\n')
+    )
+  }
+  return { activeHeading, activeNavigationHeading }
+}
+
+function getHeadingsAll<T extends Heading | HeadingDetached>(
+  headingsProcessed: T[],
+  pageContext: { exports: Exports; urlOriginal: string },
+  activeHeading: T
+): T[] {
+  const headingsAll = headingsProcessed.slice()
+
+  const headingsOfTheCurrentPage = getHeadingsOfTheCurrentPage(pageContext, activeHeading)
+
+  const activeHeadingIdx = headingsAll.indexOf(activeHeading)
+  assert(activeHeadingIdx >= 0)
+  headingsOfTheCurrentPage.forEach((pageHeading, i) => {
+    headingsAll.splice(activeHeadingIdx + 1 + i, 0, pageHeading as T)
+  })
+
+  return headingsAll
+}
+
+function getHeadingsOfTheCurrentPage(
+  pageContext: { exports: Exports; urlOriginal: string },
+  currentHeading: Heading | HeadingDetached
+) {
+  const headingsOfCurrentPage: Heading[] = []
+
+  const headingsExport = pageContext.exports.headings ?? []
+
+  headingsExport.forEach((markdownHeading) => {
+    const title = parseTitle(markdownHeading.title)
+    const url: null | string = markdownHeading.headingId && '#' + markdownHeading.headingId
+    if (markdownHeading.headingLevel === 2) {
+      const heading: Heading = {
+        url,
+        title,
+        headingsBreadcrumb: [currentHeading, ...(currentHeading.headingsBreadcrumb ?? [])],
+        titleInNav: title,
+        level: 3
+      }
+      headingsOfCurrentPage.push(heading)
+    }
+  })
+
+  if (currentHeading?.sectionTitles) {
+    currentHeading.sectionTitles.forEach((sectionTitle) => {
+      const pageHeadingTitles = headingsExport.map((h) => h.title)
+      assert(pageHeadingTitles.includes(sectionTitle), { pageHeadingTitles, sectionTitle })
+    })
+  }
+
+  return headingsOfCurrentPage
+}

package/css/button.css

@@ -0,0 +1,7 @@
+button,
+a.button {
+  background-color: #fafafa;
+  border: 1px solid #aaa;
+  border-radius: 5px;
+  cursor: pointer;
+}

package/css/code/block.css

@@ -0,0 +1,36 @@
+pre > code {
+  padding: 16px !important;
+}
+@media screen and (max-width: 900px) {
+  pre > code {
+    font-size: 0.7em;
+  }
+}
+pre {
+  display: grid;
+}
+pre > code {
+  padding-right: 0px !important;
+  overflow-x: auto;
+}
+
+@media screen and (max-width: 1139px) {
+  pre > code {
+    font-size: 0.95em;
+  }
+}
+@media screen and (max-width: 1040px) {
+  pre > code {
+    font-size: 0.8em;
+  }
+}
+@media screen and (max-width: 940px) {
+  pre > code {
+    font-size: 0.7em;
+  }
+}
+
+pre > code {
+  display: reset;
+  word-break: reset;
+}

package/css/code/inline.css

@@ -0,0 +1,27 @@
+code {
+  padding: 2px 5px;
+}
+
+/*
+ * Line breaks in `<code>`:
+ *  - Avoid them on desktop
+ *  - Allow them on mobile
+ *  - Allo them for `<code long>`
+ */
+code {
+  display: inline-block;
+}
+@media screen and (max-width: 500px) {
+  code {
+    word-break: break-word;
+    display: inline;
+  }
+}
+.inline-code-break code {
+  display: inline;
+  word-break: break-word;
+}
+code.long {
+  word-break: break-word;
+  display: inline;
+}

package/css/code.css

@@ -0,0 +1,20 @@
+@import './code/inline.css';
+@import './code/block.css';
+
+code {
+  /*
+  background-color: #f4f4f4;
+  0.043137255 = 1 - (#f4 / #ff)
+  */
+  background-color: rgba(0, 0, 0, 0.043137255);
+  border-radius: 4px;
+}
+
+/* Inline */
+code {
+  font-size: 1.1em;
+}
+/* Block */
+pre > code {
+  font-size: 1em;
+}

package/css/colorize-on-hover.css

@@ -0,0 +1,29 @@
+.colorize-on-hover,
+.colorize-on-hover [class^='decolorize-'],
+.colorize-on-hover [class*=' decolorize-'] {
+  transition: filter 0.3s ease-in-out;
+}
+.colorize-on-hover:hover,
+.colorize-on-hover:hover [class^='decolorize-'],
+.colorize-on-hover:hover [class*=' decolorize-'] {
+  filter: grayscale(0) opacity(1) !important;
+}
+
+.decolorize-7 {
+  filter: grayscale(1) opacity(0.7);
+}
+.decolorize-6 {
+  filter: grayscale(1) opacity(0.6);
+}
+.decolorize-5 {
+  filter: grayscale(1) opacity(0.5);
+}
+.decolorize-4 {
+  filter: grayscale(1) opacity(0.4);
+}
+
+/*
+ * Twitter opacity(0.7): #ababab > #868686
+ * == Following computation does NOT work ==
+ * Discord opacity(0.7): #6c6c6c > (0.7 * (#fff - #ababab) = #868686 = x * (#fff - #6c6c6c) <=> x = 0.7 * ((#fff - #ababab) / (#fff - #6c6c6c)) = 0.7 * ((255 - 171) / (255 - 108)) = 0.4)
+ */

package/css/font.css

@@ -0,0 +1,25 @@
+body {
+  font-family: 'Inter';
+}
+button {
+  font-family: inherit;
+}
+body {
+  --color-text: #323d48;
+  color: var(--color-text);
+  line-height: 1.5;
+}
+
+@font-face {
+  font-family: 'Inter';
+  font-weight: 100 900;
+  font-stretch: 75% 125%;
+  font-style: oblique 0deg 12deg;
+  src: url('./Inter-Var.ttf') format('truetype-variations');
+}
+
+em,
+i {
+  font-variation-settings: 'slnt' -10;
+  font-style: normal;
+}

package/css/heading.css

@@ -0,0 +1,45 @@
+.doc-page h2,
+.doc-page h3 {
+  margin-bottom: 16px;
+}
+.doc-page h2 {
+  margin-top: 50px;
+}
+.doc-page h3 {
+  margin-top: 40px;
+}
+
+.doc-page h1 + h2,
+.doc-page h1 + h3,
+.doc-page h2 + h3 {
+  margin-top: 0;
+}
+
+.doc-page h4 {
+  margin-top: 32px;
+  margin-bottom: 16px;
+}
+
+.doc-page h5 {
+  font-size: 0.94em;
+  color: #777;
+  margin-bottom: 10px;
+}
+
+/***************/
+/** Clickable **/
+/***************/
+.doc-page h2[id],
+.doc-page h3[id] {
+  cursor: pointer;
+  position: relative;
+  padding-left: 26px;
+  margin-left: -26px;
+}
+.doc-page h2[id]:hover::before,
+.doc-page h3[id]:hover::before {
+  content: '#';
+  position: absolute;
+  left: calc(-1 * (0.75em - 26px));
+  color: #aaa;
+}

package/css/index.css

@@ -0,0 +1,12 @@
+@import './reset.css';
+@import './colorize-on-hover.css';
+@import './heading.css';
+@import './button.css';
+@import './link.css';
+@import './font.css';
+@import './code.css';
+@import './table.css';
+@import './tooltip.css';
+@import '../algolia/DocSearch.css';
+@import '../components/Note.css';
+@import '../components/CodeBlockTransformer.css';

package/css/link.css

@@ -0,0 +1,17 @@
+/*
+:root {
+  --link-color: #4747ff;
+}
+*/
+
+a {
+  /*
+  color: inherit;
+  color: var(--link-color);
+  */
+  color: #4747ff;
+  text-decoration: none;
+}
+a > button {
+  color: var(--color-text);
+}

package/css/reset.css

@@ -0,0 +1,12 @@
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+}
+
+/* Avoid tweet embeds to overflow the body width.
+ * Settings `overflow: hidden` to a container doesn't work (This is a CSS bug?) */
+iframe {
+  max-width: 100%;
+}