@brillout/docpress 0.5.39 → 0.5.40-commit-1ba896e

package/MobileHeader.tsx

@@ -0,0 +1,68 @@
+import React from 'react'
+import { usePageContext } from './renderer/usePageContext'
+
+export { MobileHeader }
+
+function MobileHeader() {
+  const pageContext = usePageContext()
+  return (
+    <div
+      id="mobile-header"
+      style={{
+        height: 'var(--mobile-header-height)',
+        width: '100%',
+        position: 'relative'
+      }}
+    >
+      <div
+        style={{
+          position: 'fixed',
+          display: 'flex',
+          alignItems: 'center',
+          background: 'white',
+          zIndex: 99,
+          top: 0,
+          left: 0,
+          height: 'var(--mobile-header-height)',
+          width: '100%',
+          borderBottom: '1px solid #ddd'
+        }}
+      >
+        <MenuToggle />
+        <a
+          href="/"
+          style={{
+            color: 'inherit',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'left',
+            textDecoration: 'none',
+            ...pageContext.config.navHeaderMobileWrapperStyle
+          }}
+        >
+          {pageContext.config.navHeaderMobile}
+        </a>
+      </div>
+    </div>
+  )
+}
+
+function MenuToggle() {
+  return (
+    <div style={{ padding: 20, lineHeight: 0, cursor: 'pointer' }} id="menu-toggle">
+      <svg
+        style={{ width: 20 }}
+        className="icon"
+        xmlns="http://www.w3.org/2000/svg"
+        aria-hidden="true"
+        role="img"
+        viewBox="0 0 448 512"
+      >
+        <path
+          fill="currentColor"
+          d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"
+        ></path>
+      </svg>
+    </div>
+  )
+}

package/PageLayout.css

@@ -0,0 +1,42 @@
+.doc-page #page-container {
+  padding-bottom: 100px;
+}
+
+#page-layout {
+  display: flex;
+  justify-content: center;
+  width: 100%;
+}
+#page-layout > #navigation-wrapper,
+#page-layout > #page-wrapper {
+  flex-grow: 1;
+}
+/* Avoid overflow, see https://stackoverflow.com/questions/36230944/prevent-flex-items-from-overflowing-a-container/66689926#66689926 */
+#page-layout > #page-wrapper {
+  min-width: 0;
+}
+
+.doc-page #page-wrapper {
+  --main-view-max-width: 800px;
+}
+.landing-page #page-wrapper {
+  --main-view-max-width: 1010px;
+}
+#page-wrapper {
+  max-width: calc(var(--main-view-max-width) + 80px);
+}
+#page-content {
+  box-sizing: content-box;
+  max-width: var(--main-view-max-width);
+  padding: 20px var(--main-view-padding);
+  margin: auto;
+}
+
+#page-content {
+  --main-view-padding: 20px;
+}
+@media screen and (max-width: 1139px) {
+  #page-content {
+    --main-view-padding: 10px;
+  }
+}

package/PageLayout.tsx

@@ -0,0 +1,39 @@
+import React from 'react'
+import { Navigation, NavigationMask } from './navigation/Navigation'
+import type { PageContextResolved } from './config/resolvePageContext'
+import { MobileHeader } from './MobileHeader'
+import { EditPageNote } from './components/EditPageNote'
+import { PageContextProvider } from './renderer/usePageContext'
+import './PageLayout.css'
+import { NavigationFullscreenButton } from './navigation/navigation-fullscreen/NavigationFullscreenButton'
+
+export { PageLayout }
+
+function PageLayout({ pageContext, children }: { pageContext: PageContextResolved; children: React.ReactNode }) {
+  const { isLandingPage, pageTitle } = pageContext
+  const { globalNote } = pageContext.config
+  return (
+    <React.StrictMode>
+      <PageContextProvider pageContext={pageContext}>
+        <div id="page-layout" className={isLandingPage ? 'landing-page' : 'doc-page'}>
+          <div id="navigation-wrapper">
+            <Navigation pageContext={pageContext} />
+          </div>
+          <NavigationFullscreenButton />
+          <div id="page-wrapper">
+            <div id="page-container">
+              <MobileHeader />
+              <div id="page-content">
+                {globalNote}
+                {pageTitle && <h1>{pageTitle}</h1>}
+                {children}
+                {!isLandingPage && <EditPageNote pageContext={pageContext} />}
+              </div>
+            </div>
+            <NavigationMask />
+          </div>
+        </div>
+      </PageContextProvider>
+    </React.StrictMode>
+  )
+}

package/algolia/DocSearch.css

@@ -0,0 +1,34 @@
+.DocSearch-Button-Keys {
+  margin-left: 6px !important;
+}
+.DocSearch-Search-Icon {
+  margin-right: 0 !important;
+}
+.DocSearch-Button-Placeholder {
+  padding-right: 6px !important;
+}
+
+#docsearch-desktop {
+  max-width: 110px !important;
+}
+#docsearch-desktop .DocSearch-Button-Placeholder,
+#docsearch-desktop .DocSearch-Button-Keys {
+  display: none;
+}
+#docsearch-desktop .DocSearch-Button {
+  background: transparent !important;
+  padding: 0 !important;
+  position: relative;
+  top: -1px;
+  outline: none !important;
+  border: none !important;
+  box-shadow: none !important;
+}
+#docsearch-desktop .DocSearch-Search-Icon {
+  height: 21px !important;
+  width: 21px !important;
+}
+#docsearch-desktop .DocSearch-Button {
+  margin-right: 3px !important;
+  margin-left: 1px !important;
+}

package/algolia/DocSearch.ts

@@ -0,0 +1,62 @@
+export { getDocSearchCSS }
+export { getDocSearchJS }
+
+import { dangerouslySkipEscape, escapeInject } from 'vike/server'
+import { PageContextResolved } from '../config/resolvePageContext'
+/* Imorted in /src/css/index.css instead
+import './DocSearch.css'
+*/
+
+function getDocSearchCSS(pageContext: PageContextResolved) {
+  const docSearchCSS = !pageContext.meta.algolia
+    ? ''
+    : escapeInject`
+      <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@alpha" />
+    `
+  return docSearchCSS
+}
+
+function getDocSearchJS(pageContext: PageContextResolved) {
+  const { algolia } = pageContext.meta
+  // If the docpress website doesn't use algolia => we don't inject the algolia assets => the search icon wrapper stays empty
+  // If algolia is PENDING_APPROVAL => we fill a FAKE API key so that the algolia popup shows (while no results are shown).
+  //  - We show an alert warning users that there aren't any results until algolia's approval is pending (see below).
+  let docSearchJS = !algolia
+    ? ''
+    : escapeInject`
+    <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@docsearch/js@alpha"></script>
+    <script type="text/javascript">
+      const appId = '${algolia.appId || 'FAKE'}';
+      const apiKey = '${algolia.apiKey || 'FAKE'}';
+      const indexName = '${algolia.indexName || 'FAKE'}';
+      const transformItems = ${dangerouslySkipEscape(getTransformItems())};
+      docsearch({
+        container: '#docsearch-desktop',
+        appId, apiKey, indexName, transformItems,
+        insights: true,
+      });
+    </script>
+  `
+  if (algolia?.PENDING_APPROVAL) {
+    docSearchJS = escapeInject`
+    ${docSearchJS}
+    <script>document.getElementById('docsearch-desktop').addEventListener('click', () => window.alert("Algolia approval is pending: the search results may be empty until the approval process is completed."))</script>
+    `
+  }
+  return docSearchJS
+}
+
+// Remove superfluous hash '#page-content' from URLs pointing to whole pages
+//  - https://github.com/algolia/docsearch/issues/1801
+//  - https://discourse.algolia.com/t/how-to-avoid-hash-in-search-result-url/6486
+//  - https://discourse.algolia.com/t/docsearchs-transformdata-function-cannot-remove-hashes-from-result-urls/8487
+function getTransformItems() {
+  return `function(hits) {
+        hits.map(hit => {
+          if (hit.url.indexOf('#page-content') > 0) {
+            hit.url = hit.url.replace('#page-content', '');
+          }
+        });
+        return hits;
+      }`
+}

package/autoScrollNav.ts

@@ -0,0 +1,36 @@
+import { assert } from './utils/client'
+
+autoScrollNav()
+
+function autoScrollNav() {
+  const navigationEl = document.getElementById('navigation-content-main')
+  assert(navigationEl)
+  const href = window.location.pathname
+  const navLinks: HTMLElement[] = Array.from(navigationEl.querySelectorAll(`a[href="${href}"]`))
+  assert(navLinks.length <= 1, { navLinks, href })
+  const navLink = navLinks[0]
+  if (!navLink) return
+
+  /* Doesn't work: the scrolling is off by hundreds of px (I guess because this function runs too early while the page is still rendering)
+  const navigationContainerEl = document.getElementById("navigation-container")
+  const offset = navLink.offsetTop - (window.innerHeight / 2)
+  navigationContainerEl.scrollTop = offset
+  */
+
+  /* Doesn't work: scrollIntoView() still scrolls the main view
+  const overflowOriginal = document.documentElement.style.overflow
+  document.documentElement.style.overflow = 'hidden'
+  ...
+  document.documentElement.style.overflow = overflowOriginal
+  */
+
+  const scrollTopOriginal = document.documentElement.scrollTop
+  navLink.scrollIntoView({
+    // @ts-ignore https://github.com/microsoft/TypeScript/issues/46654
+    behavior: 'instant',
+    block: 'center',
+    inline: 'start'
+  })
+  // Avoid scrollIntoView() from scrolling the main view. Alternatively, we could use scrollIntoViewIfNeeded() (https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewIfNeeded) which doesn't scroll the main view but Firefox doesn't support it.
+  document.documentElement.scrollTop = scrollTopOriginal
+}

package/components/CodeBlockTransformer.css

@@ -0,0 +1,9 @@
+.with-line-break_white-space code,
+.with-line-break_break-word code {
+  white-space: break-spaces;
+  padding-right: 16px !important;
+}
+.with-line-break_break-word code {
+  word-wrap: break-word;
+  word-break: break-all;
+}

package/components/CodeBlockTransformer.tsx

@@ -0,0 +1,18 @@
+export { CodeBlockTransformer }
+
+import React from 'react'
+import { assert } from '../utils/server'
+/* Imorted in /src/css/index.css instead
+import './CodeBlockTransformer.css'
+*/
+
+type LineBreak = 'white-space' | 'break-word'
+
+function CodeBlockTransformer({ children, lineBreak }: { children: React.ReactNode; lineBreak: LineBreak }) {
+  assert(
+    lineBreak === 'white-space' || lineBreak === 'break-word',
+    '`lineBreak` is currently the only use case for <CodeBlockTransformer>'
+  )
+  const className = `with-line-break_${lineBreak}` as const
+  return <div className={className}>{children}</div>
+}

package/components/Comment.tsx

@@ -0,0 +1,7 @@
+export { Comment }
+
+import React from 'react'
+
+function Comment({ children }: { children: React.ReactNode }) {
+  return <></>
+}

package/components/Consulting.tsx

@@ -0,0 +1,47 @@
+export { Consulting, Consultants }
+
+import React from 'react'
+import iconPeople from '../icons/people.svg'
+import { usePageContext } from '../renderer/usePageContext'
+import { SupporterSection, SectionDescription, CallToAction } from './Supporters'
+import { Maintainer } from './Contributors'
+import { maintainers } from '../data/maintainersList'
+import { Link } from './Link'
+const consultingPageHref = '/consulting'
+
+function Consulting() {
+  const pageContext = usePageContext()
+  const { projectInfo } = pageContext.config
+  const { projectName } = projectInfo
+  return (
+    <SupporterSection>
+      <CallToAction iconUrl={iconPeople} text="Consulting" href={consultingPageHref} />
+      <div></div>
+      <SectionDescription>
+        For questions and issues related to {projectName}, open a{' '}
+        <a href={projectInfo.githubDiscussions || projectInfo.githubIssues}>GitHub Discussion</a>. For advanced help or
+        help not directly related to {projectName}, the {projectName} team offers{' '}
+        <Link href={consultingPageHref} noBreadcrumb>
+          consulting
+        </Link>
+        .
+      </SectionDescription>
+    </SupporterSection>
+  )
+}
+
+function Consultants() {
+  return (
+    <SupporterSection>
+      <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'end' }}>
+        {maintainers
+          .filter((maintainer) => {
+            return !!maintainer.consultingUrl
+          })
+          .map((maintainer, i) => (
+            <Maintainer maintainer={maintainer} key={i} />
+          ))}
+      </div>
+    </SupporterSection>
+  )
+}

package/components/Contributors.tsx

@@ -0,0 +1,113 @@
+export { Contributors, Maintainer }
+
+import React from 'react'
+import { usePageContext } from '../renderer/usePageContext'
+import { Supporter, SupporterSection, SectionDescription, Individuals, SupporterImg } from './Supporters'
+import { maintainers } from '../data/maintainersList'
+import { contributors } from 'vike-contributors' // sorted by number of contributions
+
+function Contributors() {
+  const pageContext = usePageContext()
+  const { projectInfo } = pageContext.config
+  return (
+    <SupporterSection>
+      <SectionDescription>
+        {projectInfo.projectName} is built and maintained by passionate contributors.
+      </SectionDescription>
+      <div style={{ display: 'flex', flexWrap: 'wrap', justifyContent: 'space-evenly', alignItems: 'end' }}>
+        {maintainers.map((maintainer, i) => (
+          <Maintainer maintainer={maintainer} key={i} />
+        ))}
+      </div>
+      <Individuals>
+        {contributors
+          .filter((contributor) => {
+            return (
+              !contributor.login.includes('[bot]') && !maintainers.map((m) => m.username).includes(contributor.login)
+            )
+          })
+          .map((contributor, i) => (
+            <Supporter username={contributor.login} avatarUrl={contributor.avatarUrl} key={i} />
+          ))}
+      </Individuals>
+    </SupporterSection>
+  )
+}
+
+function Maintainer({ maintainer }: { maintainer: (typeof maintainers)[0] }) {
+  const marginHeight = 20
+  const marginWidth = 10
+  const imgSize = 50
+  const githubUrl = `https://github.com/${maintainer.username}`
+  return (
+    <div
+      style={{
+        borderRadius: 7,
+        borderWidth: 1,
+        borderStyle: 'solid',
+        borderColor: '#e0e0e0',
+        overflow: 'hidden',
+        width: 430,
+        maxWidth: `calc(100vw - 2 * var(--main-view-padding) - 2 * ${marginWidth}px)`,
+        margin: `${marginHeight}px ${marginWidth}px`,
+        display: 'flex',
+        flexWrap: 'wrap',
+        padding: 20,
+        gap: 20,
+        textAlign: 'left'
+      }}
+    >
+      <a href={githubUrl}>
+        <div style={{ width: imgSize, height: imgSize, borderRadius: imgSize / 2, overflow: 'hidden' }}>
+          <SupporterImg
+            username={maintainer.username}
+            avatarUrl={getAvatarUrl(maintainer)}
+            imgAlt={maintainer.firstName}
+            width={imgSize}
+            height={imgSize}
+          />
+        </div>
+      </a>
+      <div>
+        <b>{maintainer.firstName}</b> ·{' '}
+        <a href={githubUrl}>
+          <i style={{ fontSize: '.9em', color: '#505050' }}>{maintainer.username}</i>
+        </a>
+        {maintainer.consultingUrl ? (
+          <>
+            {' '}
+            ·{' '}
+            <a href={maintainer.consultingUrl}>
+              <b
+                style={{
+                  fontSize: '.7em',
+                  color: 'white',
+                  backgroundColor: '#305090',
+                  padding: '1px 5px 2px 5px',
+                  verticalAlign: 'text-top',
+                  borderRadius: 3
+                }}
+              >
+                consulting
+              </b>
+            </a>
+          </>
+        ) : null}
+        <ul style={{ fontSize: '.8em', paddingLeft: 15, marginTop: 5, marginBottom: 0 }}>
+          {maintainer.roles.map((role, i) => (
+            <li key={i}>{role}</li>
+          ))}
+        </ul>
+      </div>
+    </div>
+  )
+}
+
+function getAvatarUrl(maintainer: (typeof maintainers)[0]) {
+  for (const contributor of contributors) {
+    if (maintainer.username === contributor.login) {
+      return contributor.avatarUrl
+    }
+  }
+  throw new Error(`Maintainer ${maintainer.username} not found in contributors' list.`)
+}

package/components/EditPageNote.tsx

@@ -0,0 +1,18 @@
+import React from 'react'
+import { RepoLink } from './RepoLink'
+import { Emoji } from '../utils/server'
+
+export { EditPageNote }
+
+function EditPageNote({ pageContext }: { pageContext: { urlPathname: string } }) {
+  const text = (
+    <>
+      <Emoji name="writing-hang" /> Edit this page
+    </>
+  )
+  return (
+    <div style={{ marginTop: 50 }}>
+      <RepoLink path={'/docs/pages' + pageContext.urlPathname + '/+Page.mdx'} text={text} editMode={true} />
+    </div>
+  )
+}

package/components/HorizontalLine.tsx

@@ -0,0 +1,20 @@
+import React from 'react'
+
+export { HorizontalLine }
+
+function HorizontalLine({ primary }: { primary?: true }) {
+  return (
+    <div className={'header-separator-line ' + (primary ? 'primary' : '')} style={{ textAlign: 'center' }}>
+      <hr
+        style={{
+          display: 'inline-block',
+          margin: 0,
+          border: 0,
+          borderTop: '1px solid #eee',
+          maxWidth: 500,
+          width: '80%'
+        }}
+      />
+    </div>
+  )
+}

package/components/ImportMeta.tsx

@@ -0,0 +1,11 @@
+import React from 'react'
+import { assert } from '../utils/server'
+
+export { ImportMeta }
+
+function ImportMeta({ prop }: { prop: string }) {
+  assert(!prop.startsWith('import'))
+  assert(!prop.startsWith('.'))
+  const text = 'imp' + 'ort.meta.' + prop
+  return <code>{text}</code>
+}

package/components/Link.tsx

@@ -0,0 +1,144 @@
+export { Link }
+
+import React from 'react'
+import { isRepoLink, RepoLink } from './RepoLink'
+import type { Heading, HeadingDetached } from '../types/Heading'
+import type { PageContextResolved } from '../config/resolvePageContext'
+import { usePageContext } from '../renderer/usePageContext'
+import { assert, assertUsage, determineSectionTitle, determineSectionUrlHash } from '../utils/server'
+import { parseTitle } from '../parseTitle'
+
+function Link({
+  href,
+  text,
+  noBreadcrumb,
+  doNotInferSectionTitle,
+  children
+}: {
+  href: string
+  text?: string | JSX.Element
+  noBreadcrumb?: true
+  doNotInferSectionTitle?: true
+  children?: React.ReactNode
+}) {
+  assertUsage(
+    href.startsWith('/') || href.startsWith('#'),
+    `<Link href /> prop \`href==='${href}'\` but should start with '/' or '#'`
+  )
+  assertUsage(!text || !children, 'Cannot use both `text` or `children`')
+
+  if (isRepoLink(href)) {
+    return <RepoLink path={href} text={text} />
+  } else {
+    const pageContext = usePageContext()
+    return (
+      <a href={href}>{children || text || getLinkText({ href, noBreadcrumb, pageContext, doNotInferSectionTitle })}</a>
+    )
+  }
+}
+
+function getLinkText({
+  href,
+  noBreadcrumb,
+  pageContext,
+  doNotInferSectionTitle
+}: {
+  href: string
+  noBreadcrumb: true | undefined
+  pageContext: PageContextResolved
+  doNotInferSectionTitle: true | undefined
+}): string | JSX.Element {
+  let urlHash: string | null = null
+  let hrefWithoutHash: string = href
+  if (href.includes('#')) {
+    ;[hrefWithoutHash, urlHash] = href.split('#')
+    assert(hrefWithoutHash || urlHash)
+  }
+
+  let heading: Heading | HeadingDetached
+  let isLinkOnSamePage: boolean = false
+  if (hrefWithoutHash) {
+    heading = findHeading(hrefWithoutHash, pageContext)
+    if (heading.url === pageContext.urlPathname) {
+      isLinkOnSamePage = true
+      // heading !== pageContext.activeHeading because activeHeading is a different object holding on-this-page subheadings
+      heading = pageContext.activeHeading
+    }
+  } else {
+    assert(urlHash)
+    isLinkOnSamePage = true
+    heading = pageContext.activeHeading
+  }
+  assert(heading)
+  assert(isLinkOnSamePage === (heading.url === pageContext.urlPathname))
+  assert(isLinkOnSamePage === (heading.url === pageContext.activeHeading.url))
+  assert(isLinkOnSamePage === (heading === pageContext.activeHeading))
+
+  const breadcrumbParts: (string | JSX.Element)[] = []
+
+  if (heading.headingsBreadcrumb) {
+    breadcrumbParts.push(
+      ...(heading.headingsBreadcrumb ?? [])
+        .slice()
+        .reverse()
+        .map(({ title }) => title)
+    )
+  }
+
+  breadcrumbParts.push(heading.title)
+
+  if (urlHash) {
+    let sectionTitle: string | JSX.Element | undefined = undefined
+    assert(!urlHash.startsWith('#'))
+    if (isLinkOnSamePage) {
+      const pageHeading = findHeading(`#${urlHash}`, pageContext)
+      sectionTitle = pageHeading.title
+    } else if ('sectionTitles' in heading && heading.sectionTitles) {
+      heading.sectionTitles.forEach((title) => {
+        if (determineSectionUrlHash(title) === urlHash) {
+          sectionTitle = parseTitle(title)
+        }
+      })
+    }
+    if (!sectionTitle) {
+      assertUsage(
+        !doNotInferSectionTitle,
+        `Page section title not found for <Link href="\`${href}\`" doNotInferSectionTitle={true} />.`
+      )
+      sectionTitle = determineSectionTitle(href)
+    }
+    breadcrumbParts.push(sectionTitle)
+  }
+
+  {
+    if (noBreadcrumb || isLinkOnSamePage) {
+      return breadcrumbParts[breadcrumbParts.length - 1]
+    }
+  }
+
+  return (
+    <>
+      {breadcrumbParts.map((title, i) => {
+        const seperator = i === 0 ? <></> : ' > '
+        return (
+          <React.Fragment key={i}>
+            {seperator}
+            {title}
+          </React.Fragment>
+        )
+      })}
+    </>
+  )
+}
+
+function findHeading(href: string, pageContext: PageContextResolved): Heading | HeadingDetached {
+  assert(href.startsWith('/') || href.startsWith('#'))
+  const { headingsAll } = pageContext
+  const heading = headingsAll.find(({ url }) => href === url)
+  if (href.startsWith('#')) {
+    assertUsage(heading, `Couldn't find ${href} in ${pageContext.urlPathname}, does it exist?`)
+  } else {
+    assertUsage(heading, `Couldn't find heading for ${href}, did you define the heading for ${href}?`)
+  }
+  return heading
+}