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

[docs-infra] Support rendering markdown outside of docs #37691

Merged
merged 1 commit into from
Jun 24, 2023
Merged

[docs-infra] Support rendering markdown outside of docs #37691

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 1 addition & 1 deletion docs/src/modules/components/AppLayoutDocs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ function AppLayoutDocs(props) {
*/}
<StyledAppContainer disableAd={disableAd} hasTabs={hasTabs}>
<ActionsDiv>
<EditPage markdownLocation={location} />
<EditPage sourceLocation={location} />
</ActionsDiv>
{children}
<NoSsr>
Expand Down
10 changes: 5 additions & 5 deletions docs/src/modules/components/AppLayoutDocsWithoutAppFrame.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ const ActionsDiv = styled('div')(({ theme }) => ({
},
}));

function AppLayoutDocs(props) {
function AppLayoutDocsWithoutAppFrame(props) {
const router = useRouter();
const {
children,
Expand Down Expand Up @@ -133,7 +133,7 @@ function AppLayoutDocs(props) {
*/}
<StyledAppContainer disableAd={disableAd} hasTabs={hasTabs}>
<ActionsDiv>
<EditPage markdownLocation={location} />
<EditPage sourceLocation={location} />
</ActionsDiv>
{children}
<NoSsr>
Expand All @@ -148,7 +148,7 @@ function AppLayoutDocs(props) {
);
}

AppLayoutDocs.propTypes = {
AppLayoutDocsWithoutAppFrame.propTypes = {
children: PropTypes.node.isRequired,
description: PropTypes.string.isRequired,
disableAd: PropTypes.bool.isRequired,
Expand All @@ -160,7 +160,7 @@ AppLayoutDocs.propTypes = {
};

if (process.env.NODE_ENV !== 'production') {
AppLayoutDocs.propTypes = exactProp(AppLayoutDocs.propTypes);
AppLayoutDocsWithoutAppFrame.propTypes = exactProp(AppLayoutDocsWithoutAppFrame.propTypes);
}

export default AppLayoutDocs;
export default AppLayoutDocsWithoutAppFrame;
11 changes: 6 additions & 5 deletions docs/src/modules/components/EditPage.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,22 @@ import Button from '@mui/material/Button';
import { useUserLanguage, useTranslate } from 'docs/src/modules/utils/i18n';
import GitHubIcon from '@mui/icons-material/GitHub';

const LOCALES = { zh: 'zh-CN', pt: 'pt-BR', es: 'es-ES' };

export default function EditPage(props) {
const { markdownLocation } = props;
const { sourceLocation } = props;
const t = useTranslate();
const userLanguage = useUserLanguage();
const LOCALES = { zh: 'zh-CN', pt: 'pt-BR', es: 'es-ES' };
const CROWDIN_ROOT_URL = 'https://translate.mui.com/project/material-ui-docs/';
const crowdInLocale = LOCALES[userLanguage] || userLanguage;
const crowdInPath = markdownLocation.substring(0, markdownLocation.lastIndexOf('/'));
const crowdInPath = sourceLocation.substring(0, sourceLocation.lastIndexOf('/'));

return (
<Button
component="a"
href={
userLanguage === 'en'
? `${process.env.SOURCE_CODE_ROOT_URL}${markdownLocation}`
? `${process.env.SOURCE_CODE_ROOT_URL}${sourceLocation}`
: `${CROWDIN_ROOT_URL}${crowdInLocale}#/${process.env.SOURCE_CODE_ROOT_URL.replace(
'https://github.com/mui/',
'',
Expand Down Expand Up @@ -52,5 +53,5 @@ export default function EditPage(props) {
}

EditPage.propTypes = {
markdownLocation: PropTypes.string.isRequired,
sourceLocation: PropTypes.string.isRequired,
};
6 changes: 3 additions & 3 deletions docs/src/modules/components/MarkdownDocsV2.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import HooksApiContent from 'docs/src/modules/components/HooksApiContent';
import { getTranslatedHeader as getComponentTranslatedHeader } from 'docs/src/modules/components/ApiPage';
import MarkdownElement from 'docs/src/modules/components/MarkdownElementV2';
import { pathnameToLanguage } from 'docs/src/modules/utils/helpers';
import AppLayoutDocs from 'docs/src/modules/components/AppLayoutDocsWithoutAppFrame';
import AppLayoutDocsWithoutAppFrame from 'docs/src/modules/components/AppLayoutDocsWithoutAppFrame';
import { useTranslate, useUserLanguage } from 'docs/src/modules/utils/i18n';
import BrandingProvider from 'docs/src/BrandingProvider';
import Ad from 'docs/src/modules/components/Ad';
Expand Down Expand Up @@ -211,7 +211,7 @@ export default function MarkdownDocsV2(props) {
}

return (
<AppLayoutDocs
<AppLayoutDocsWithoutAppFrame
description={description}
disableAd={disableAd}
disableToc={disableToc}
Expand Down Expand Up @@ -270,7 +270,7 @@ export default function MarkdownDocsV2(props) {
)}
</Provider>
</div>
</AppLayoutDocs>
</AppLayoutDocsWithoutAppFrame>
);
}

Expand Down
11 changes: 7 additions & 4 deletions packages/markdown/loader.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,12 +121,15 @@ module.exports = async function demoLoader() {
}),
);

const pageFilename = this.context
.replace(this.rootContext, '')
// Use .. as the docs runs from the /docs folder
const repositoryRoot = path.join(this.rootContext, '..');
const fileRelativeContext = path
.relative(repositoryRoot, this.context)
// win32 to posix
.replace(/\\/g, '/');

const { docs } = prepareMarkdown({
pageFilename,
fileRelativeContext,
translations,
componentPackageMapping,
options,
Expand Down Expand Up @@ -157,7 +160,7 @@ module.exports = async function demoLoader() {
// The import paths currently use a completely different format.
// They should just use relative imports.
let moduleID = `./${demoName.replace(
`pages/${pageFilename.replace(/^\/src\/pages\//, '')}/`,
`pages/${fileRelativeContext.replace(/^docs\/src\/pages\//, '')}/`,
Copy link
Member

Choose a reason for hiding this comment

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

Mostly stylistic, but this line feels a bit strange. Isn't

`pages/${fileRelativeContext.replace(/^docs\/src\/pages\//, '')}/`

the same as

`${fileRelativeContext.replace(/^docs\/src\//, '')}/`

or even

`${path.posix.relative('docs/src', fileRelativeContext)}/`

?

Copy link
Member Author

Choose a reason for hiding this comment

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

Yeah, not sure why it was done this way.

'',
)}`;

Expand Down
6 changes: 3 additions & 3 deletions packages/markdown/parseMarkdown.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -426,11 +426,11 @@ function resolveComponentApiUrl(product, componentPkg, component) {
/**
* @param {object} config
* @param {Array<{ markdown: string, filename: string, userLanguage: string }>} config.translations - Mapping of locale to its markdown
* @param {string} config.pageFilename - posix filename relative to nextjs pages directory
* @param {string} config.fileRelativeContext - posix filename relative to repository root directory
* @param {object} config.options - provided to the webpack loader
*/
function prepareMarkdown(config) {
const { pageFilename, translations, componentPackageMapping = {}, options } = config;
const { fileRelativeContext, translations, componentPackageMapping = {}, options } = config;

const demos = {};
/**
Expand All @@ -446,7 +446,7 @@ function prepareMarkdown(config) {
.forEach((translation) => {
const { filename, markdown, userLanguage } = translation;
const headers = getHeaders(markdown);
const location = headers.filename || `/docs${pageFilename}/${filename}`;
const location = headers.filename || `/${fileRelativeContext}/${filename}`;
const title = headers.title || getTitle(markdown);
const description = headers.description || getDescription(markdown);

Expand Down
14 changes: 11 additions & 3 deletions packages/markdown/parseMarkdown.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import {

describe('parseMarkdown', () => {
const defaultParams = {
pageFilename: '/test',
fileRelativeContext: 'test/bar',
options: {
env: {},
},
Expand Down Expand Up @@ -439,7 +439,12 @@ authors:
...defaultParams,
translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
});
}).to.throw(/\[foo]\(\/foo\) in \/docs\/test\/index\.md is missing a trailing slash/);
}).to.throw(`docs-infra: Missing trailing slash. The following link:
[foo](/foo) in /test/bar/index.md is missing a trailing slash, please add it.

See https://ahrefs.com/blog/trailing-slash/ for more details.

Please report this to https://github.com/markedjs/marked.`);
});

it('should report missing leading splashes', () => {
Expand All @@ -457,7 +462,10 @@ authors:
...defaultParams,
translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
});
}).to.throw(/\[foo]\(foo\/\) in \/docs\/test\/index\.md is missing a leading slash/);
}).to.throw(`docs-infra: Missing leading slash. The following link:
[foo](foo/) in /test/bar/index.md is missing a leading slash, please add it.

Please report this to https://github.com/markedjs/marked.`);
});

it('should report title too long', () => {
Expand Down