Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Renamed getHeaders() to getHeadings() #1107

Closed
wants to merge 3 commits into from
Closed

Renamed getHeaders() to getHeadings() #1107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e6dce66
Converted bullet points from Importing Markdown section into subsecti…
felixsanz Jun 9, 2022
2ef21f4
Renamed getHeaders() to getHeadings(), according to RFC #208. Depends…
felixsanz Jun 17, 2022
3132ef2
Merge branch 'main' into felixsanz/main
sarah11918 Aug 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 24 additions & 15 deletions public/index.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -479,13 +479,13 @@ h2.heading {
margin-top: 1.5rem;
}

.header-link {
.heading-link {
font-size: 1rem;
padding: 0.1rem 0 0.1rem 0;
transition: border-inline-start-color 100ms ease-out, background-color 200ms ease-out;
}

.header-link a {
.heading-link a {
display: inline-flex;
gap: 0.5em;
width: 100%;
Expand All @@ -494,40 +494,40 @@ h2.heading {
text-decoration: none;
}

.header-link:hover,
.header-link:focus,
.header-link:focus-within {
.heading-link:hover,
.heading-link:focus,
.heading-link:focus-within {
border-inline-start-color: var(--theme-accent-secondary);
}

.header-link:hover a,
.header-link a:focus {
.heading-link:hover a,
.heading-link a:focus {
color: var(--theme-text);
text-decoration: underline;
}
.header-link svg {
.heading-link svg {
opacity: 0.6;
}
.header-link:hover svg {
.heading-link:hover svg {
opacity: 0.8;
}

.header-link.depth-3 {
.heading-link.depth-3 {
padding-inline-start: 1rem;
}
.header-link.depth-4 {
.heading-link.depth-4 {
padding-inline-start: 2rem;
}

/* Add line and padding on the left side */
.header-link {
.heading-link {
padding-inline-start: 1rem;
border-inline-start: 3px solid var(--theme-divider);
}
.header-link.depth-3 {
.heading-link.depth-3 {
padding-inline-start: 2rem;
}
.header-link.depth-4 {
.heading-link.depth-4 {
padding-inline-start: 3rem;
}

Expand All @@ -537,7 +537,7 @@ h2.heading {
padding-left: calc(1rem + 4px);
}

.header-link {
.heading-link {
border-inline-start-width: 4px;
}
}
Expand All @@ -549,9 +549,18 @@ h2.heading {
outline: 1px solid transparent;
}

<<<<<<< HEAD
@media (forced-colors: active) {
.current-header-link {
border: 1px solid CanvasText;
=======
/* Highlight TOC heading link matching the current scroll position */
.current-heading-link {
background-color: var(--theme-bg-accent);
}
.current-heading-link a {
color: var(--theme-text);
>>>>>>> 5645c1c (Renamed getHeaders() to getHeadings(), according to RFC #208. Depends on astro/#3627)
}
}

Expand Down
21 changes: 20 additions & 1 deletion src/components/PageContent/PageContent.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,18 @@ import TableOfContents from '../RightSidebar/TableOfContents';
import { getNav, useTranslations } from "../../i18n/util";
import { getLanguageFromURL } from '../../util';

<<<<<<< HEAD
const { content, currentPage } = Astro.props;
// We wrap `@astrojs/` in a span to style it separately on integration pages.
const title = content.title.replace('@astrojs/', '<span class="scope">@astrojs/</span>');
const headers = content.astro?.headers;
=======
const { content, currentPage, isFallback } = Astro.props;
const title = content.title;
const headings = content.astro?.headings;
>>>>>>> 5645c1c (Renamed getHeaders() to getHeadings(), according to RFC #208. Depends on astro/#3627)
const lang = getLanguageFromURL(Astro.canonicalURL.pathname);
const links = (await getNav(Astro)).filter((x) => !('header' in x) && x.slug) as { text: string; slug: string; }[];
const links = (await getNav(Astro)).filter((x) => !('heading' in x) && x.slug) as { text: string; slug: string; }[];
const index = links.findIndex((x) => currentPage.includes(x.slug));
const makeLinkItem = ({ text, slug }) => ({ text, link: `/${lang}/${slug}/` });
let next, previous;
Expand Down Expand Up @@ -37,6 +43,19 @@ const t = useTranslations(Astro);
<article id="article" class="content">
<section class="main-section">
<h1 class="content-title" id="overview" set:html={title} />
<<<<<<< HEAD
=======
{isFallback && <FallbackNotice />}
{headings && (
<nav class="block lg-hidden">
<TableOfContents
client:media="(max-width: 50em)"
headings={headings}
labels={{ onThisPage: t('rightSidebar.onThisPage'), overview: t('rightSidebar.overview') }}
/>
</nav>
)}
>>>>>>> 5645c1c (Renamed getHeaders() to getHeadings(), according to RFC #208. Depends on astro/#3627)
<slot />
</section>
{(previous || next) && (
Expand Down
17 changes: 16 additions & 1 deletion src/components/RightSidebar/RightSidebar.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,10 @@ import { useTranslations } from "../../i18n/util";
const t = useTranslations(Astro);

const { content, githubEditUrl } = Astro.props;
const headers = content.astro?.headers;
const headings = content.astro?.headings;
---

<<<<<<< HEAD
<nav aria-label={t('rightSidebar.a11yTitle')}>
{headers && (
<TableOfContents
Expand All @@ -21,6 +22,20 @@ const headers = content.astro?.headers;
)}
<ContributeMenu i18nReady={content.i18nReady} editHref={githubEditUrl} />
<CommunityMenu />
=======
<nav class="sidebar-nav" aria-label={t('rightSidebar.a11yTitle')}>
<div class="sidebar-nav-inner">
{headings && (
<TableOfContents
client:media="(min-width: 50em)"
headings={headings}
labels={{ onThisPage: t('rightSidebar.onThisPage'), overview: t('rightSidebar.overview') }}
/>
)}
<ContributeMenu editHref={githubEditUrl} />
<CommunityMenu />
</div>
>>>>>>> 5645c1c (Renamed getHeaders() to getHeadings(), according to RFC #208. Depends on astro/#3627)
</nav>

<style>
Expand Down
13 changes: 12 additions & 1 deletion src/components/RightSidebar/TableOfContents.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,21 @@ import { useState, useEffect, useRef } from 'preact/hooks';
import './TableOfContents.css';

interface Props {
headers: { depth: number; slug: string; text: string }[];
headings: { depth: number; slug: string; text: string }[];
labels: {
onThisPage: string;
overview: string;
};
isMobile?: boolean;
}

<<<<<<< HEAD
const TableOfContents: FunctionalComponent<Props> = ({ headers = [], labels, isMobile }) => {
headers = [{ depth: 2, slug: 'overview', text: labels.overview }, ...headers].filter(({ depth }) => depth > 1 && depth < 4);
=======
const TableOfContents: FunctionalComponent<Props> = ({ headings = [], labels }) => {
headings = [{ depth: 2, slug: 'overview', text: labels.overview }, ...headings].filter(({ depth }) => depth > 1 && depth < 4);
>>>>>>> 5645c1c (Renamed getHeaders() to getHeadings(), according to RFC #208. Depends on astro/#3627)
const toc = useRef<HTMLUListElement>();
const [currentID, setCurrentID] = useState('overview');
const [open, setOpen] = useState(!isMobile);
Expand Down Expand Up @@ -92,11 +97,17 @@ const TableOfContents: FunctionalComponent<Props> = ({ headers = [], labels, isM
</h2>
</HeadingContainer>
<ul ref={toc}>
<<<<<<< HEAD
{headers.map(({ depth, slug, text }) => (
<li class={`header-link depth-${depth} ${currentID === slug ? 'current-header-link' : ''}`.trim()}>
<a href={`#${slug}`} onClick={onLinkClick}>
{unescape(text)}
</a>
=======
{headings.map(({ depth, slug, text }) => (
<li class={`heading-link depth-${depth} ${currentID === slug ? 'current-heading-link' : ''}`.trim()}>
<a href={`#${slug}`}>{text}</a>
>>>>>>> 5645c1c (Renamed getHeaders() to getHeadings(), according to RFC #208. Depends on astro/#3627)
</li>
))}
</ul>
Expand Down
16 changes: 11 additions & 5 deletions src/pages/en/guides/markdown-content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ const { content } = Astro.props;

### Markdown Props

The `content` prop also contains an `astro` property with additional metadata about a Markdown page such as the complete Markdown `source` and a `headers` object.
The `content` prop also contains an `astro` property with additional metadata about a Markdown page such as the complete Markdown `source` and a `headings` object.

:::note
Markdown and MDX files do not return identical `content` objects. See the MDX integration guide for [MDX properties exposed](/en/guides/integrations-guide/mdx/#exported-properties).
Expand All @@ -90,7 +90,7 @@ An example blog post `content` object might look like:
"keywords": ["astro", "release", "announcement"]
**/
"astro": {
"headers": [
"headings": [
{
"depth": 1,
"text": "Astro 0.18 Release",
Expand Down Expand Up @@ -229,7 +229,7 @@ Don't forget to include a `client:directive` if necessary!

## Importing Markdown

You can import Markdown files directly into your Astro files! You can import one specific page with `import` or multiple pages with `Astro.glob()`.
You can import Markdown files directly into your Astro files! You can import one specific page with `import` or multiple with `Astro.glob()`.

```astro title="src/pages/index.astro" {3,6}
---
Expand Down Expand Up @@ -280,9 +280,15 @@ The absolute path of this file (e.g. `/home/user/projects/.../file.md`).

If it's a page, URL of the page (e.g. `/en/guides/markdown-content`).

#### `getHeadings()`

An async function that returns the headings of the Markdown file. This function returns the type: `{ depth: number; slug: string; text: string }[]`.

#### `getHeaders()`

An async function that returns the headers of the Markdown file. The response follows this type: `{ depth: number; slug: string; text: string }[]`.
:::caution[Deprecated]
The `getHeaders()` function has been renamed to `getHeadings()`. Please update your code to use `getHeadings()`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `getHeaders()` function has been renamed to `getHeadings()`. Please update your code to use `getHeadings()`.
The `getHeaders()` function has been renamed. To update an older project, please use `getHeadings()` instead.

Just a suggestion to be more explicit about which one to use. Similarly, a note about this should end up in the migration guide. (You could probably use this as-is there.)

:::

#### `rawContent()`

Expand All @@ -302,7 +308,7 @@ A function that returns the parsed HTML document as a string. Note **this does n

#### `Content`

A component that returns the full rendered contents of the Markdown file. Here is an example:
A component that renders the contents of the Markdown file. Here is an example:

```astro title="src/pages/content.astro" "Content"
---
Expand Down
2 changes: 1 addition & 1 deletion src/pages/en/reference/api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ export interface MarkdownInstance<T extends Record<string, any>> {
/* Astro Component that renders the contents of this file */
Content: AstroComponent;
/* Function that returns array of h1...h6 element in this file */
getHeaders(): Promise<{ depth: number; slug: string; text: string }[]>;
getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
}
```

Expand Down