1129.01 - Resolve links and images within the Docs Module. (directus#…

…3760)

* 1129.01 - Resolve links and images within the Docs Module. Validate hint container blocks.

* Remove copy-to-app

Co-authored-by: rijkvanzanten <[email protected]>

.gitignore

@@ -13,3 +13,4 @@ dist
 *.db
 .nyc_output
 /.idea/
+app/public/img/docs/*

app/src/modules/docs/components/markdown.vue

@@ -4,9 +4,12 @@
 
 <script lang="ts">
 import { defineComponent, ref, computed, watch, PropType, onMounted, onUpdated } from '@vue/composition-api';
+
 import marked, { Renderer } from 'marked';
 import highlight from 'highlight.js';
 
+import router from '@/router';
+
 export default defineComponent({
 	setup(props, { slots }) {
 		const html = ref('');
@@ -17,10 +20,19 @@ export default defineComponent({
 		return { html, onClick };
 
 		async function onClick($event: Event) {
-			if ($event.target instanceof HTMLElement && $event.target.classList.contains('copy')) {
-				await navigator.clipboard.writeText(
-					window.location.href.split('#')[0] + $event.target.getAttribute('href')
-				);
+			if ($event.target instanceof HTMLElement) {
+				const href = $event.target.getAttribute('href');
+				
+				if (href && $event.target.classList.contains('copy')) {
+					await navigator.clipboard.writeText(
+						window.location.href.split('#')[0] + href
+					);
+				}
+				
+				if (href && href.indexOf('/admin/docs/') === 0) {				
+					$event.preventDefault();
+					await router.push(href.replace('/admin/docs/', '/docs/'));	
+				}
 			}
 		}
 
@@ -43,6 +55,21 @@ export default defineComponent({
 						${text}
 					</h${level}>`;
 				},
+				link(href, title, text) {
+					let classname = 'body-link link';
+					
+					if (href && href.indexOf('/') === 0 && href.indexOf('/admin/docs/') === -1) href = `/admin/docs${href}`;
+					if (href && href.indexOf('#') === 0) classname = `${classname} copy`;
+					
+					return `<a href="${href}" class="${classname}">${text}</a>`;
+				},
+				image(href, title, text) {
+					let classname = 'body-image';
+					
+					if (href && href.indexOf('../assets/') === 0) href = href.replace('../assets/', '/admin/img/docs/assets/');
+					
+					return `<img src="${href}" class="${classname}" alt="${text}">`;
+				},
 			};
 
 			// Marked merges it's default rendered with our extension. It's typed as a full rendered however
@@ -54,7 +81,12 @@ export default defineComponent({
 				},
 			});
 
-			htmlString = htmlString.replace(hintRegex, (match: string, type: string, title: string, body: string) => {
+			htmlString = htmlString.replace(hintRegex, (match, type, title, body) => {		
+				if (typeof type === 'string' && type.length === 0) {
+					type = title.split(' ').shift();
+					title = title.split(' ').length > 1 ? title.split(' ').slice(1).join(' ') : title;
+				}		
+				
 				return `<div class="hint ${type}"><p class="hint-title">${title}</p><p class="hint-body">${body}</p></div>`;
 			});
 

app/src/modules/docs/routes/static.vue

@@ -1,6 +1,6 @@
 <template>
 	<private-view :title="title" ref="view">
-		<template #headline>Documentation</template>
+		<template #headline>{{ headline }}</template>
 
 		<template #title-outer:prepend>
 			<v-button rounded disabled icon>
@@ -49,26 +49,38 @@ async function getMarkdownForPath(path: string) {
 	return mdModule.default;
 }
 
+function getHeadlineFromPath(path: string) {
+	const paths = path.split('/').filter(Boolean);
+	
+	if (paths.length === 1) return 'Documentation';
+	
+	return paths[1].replace(/-/g, ' ').replace(/\b\w/g, (c) => {return c.toUpperCase()});
+}
+
 export default defineComponent({
 	name: 'StaticDocs',
 	components: { DocsNavigation, Markdown },
 	async beforeRouteEnter(to, from, next) {
 		const md = await getMarkdownForPath(to.path);
-
+		
 		next((vm: any) => {
 			vm.markdown = md;
 			vm.path = to.path;
+			vm.headline = getHeadlineFromPath(to.path);
 		});
 	},
 	async beforeRouteUpdate(to, from, next) {
 		this.markdown = await getMarkdownForPath(to.path);
 		this.path = to.path;
+		this.headline = getHeadlineFromPath(to.path);
+		
 		next();
 	},
 	setup() {
+		const headline = ref<string | null>(null);
 		const path = ref<string | null>(null);
 		const markdown = ref('');
-		const view = ref<Vue>();
+		const view = ref<Vue>();		
 
 		const title = computed(() => {
 			const firstLine = markdown.value.split('\n').shift();
@@ -80,12 +92,12 @@ export default defineComponent({
 			lines.shift();
 			return lines.join('\n');
 		});
-
+		
 		onUpdated(() => {
 			view.value?.$data.contentEl?.scrollTo({ top: 0 });
 		});
 
-		return { markdown, title, markdownWithoutTitle, view, marked, path };
+		return { markdown, headline, title, markdownWithoutTitle, view, marked, path };
 	},
 });
 </script>

docs/build.js

@@ -35,10 +35,7 @@ async function build() {
 
 	for (const yamlFile of yamlFiles) {
 		const yamlString = await fse.readFile(yamlFile, 'utf8');
-		await fse.writeJSON(
-			'./dist/' + yamlFile.replace('.yaml', '.json'),
-			yaml.safeLoad(yamlString)
-		);
+		await fse.writeJSON('./dist/' + yamlFile.replace('.yaml', '.json'), yaml.safeLoad(yamlString));
 	}
 
 	console.log(`Built docs in ${Date.now() - start} ms`);

docs/getting-started/contributing.md

@@ -22,7 +22,7 @@ our team's primary focus, we also support a community-lead PHP API port in Larav
 codebase is located in a separate git repository at [`directus/php`](https://github.com/directus).
 Though the repository is currently hidden, to coordinate contributing, please reach out to our core team via
 [Discord](https://directus.chat). 
-::: 
+:::
 <!-- prettier-ignore-end -->
 
 ## Feature Requests
@@ -136,7 +136,9 @@ npm run dev
 ```
 
 <!-- prettier-ignore-start -->
-::: If you encounter errors during this installation process, make sure your node version meets the [minimum requirements](/guides/installation/cli) :::
+::: tip
+If you encounter errors during this installation process, make sure your node version meets the [minimum requirements](/guides/installation/cli)
+:::
 <!-- prettier-ignore-end -->
 
 ### 7. Make your fixes/changes

docs/guides/extensions/api-hooks.md

@@ -30,8 +30,12 @@ System events are referenced with the format:
 
 The scope determines the API endpoint that is triggered. The `*` wildcard can also be used to include all scopes.
 
-::: System Scope Currently all system tables are available as event scopes except for `directus_migrations` and
-`directus_sessions`, which don't have relevant endpoints or services. :::
+<!-- prettier-ignore-start -->
+::: tip
+System Scope Currently all system tables are available as event scopes except for `directus_migrations` and
+`directus_sessions`, which don't have relevant endpoints or services. 
+:::
+<!-- prettier-ignore-end -->
 
 ### Action
 

docs/guides/extensions/displays.md

@@ -36,8 +36,8 @@ export default {
 -   `handler` — A function, or reference to your Vue component.
 -   `types` — A CSV of supported [types](/concepts/platform-overview#types).
 
-::: See
-[the TypeScript definition](https://github.com/directus/directus/blob/20355fee5eba514dd75565f60269311187010c66/app/src/displays/types.ts#L24-L34)
+::: tip
+See [the TypeScript definition](https://github.com/directus/directus/blob/20355fee5eba514dd75565f60269311187010c66/app/src/displays/types.ts#L24-L34)
 for more info on what can go into this object. :::
 
 ### src/display.vue

docs/guides/fields.md

@@ -1,4 +1,3 @@
-
 # Fields
 
 > You can manage your fields within the Data Model section of the App's Settings, via the

docs/guides/files.md

@@ -37,17 +37,15 @@ that you can take advantage of file permissions and other built-in features.
 5. Enter the **Fit**, **Width**, **Height**, and **Quality** for the preset
 6. Click the **Save** action button in the header
 
-<!-- prettier-ignore-start -->
-::: tip Storage Asset Transform
-The **Storage Asset Transform** can be used in conjunction with the
-presets to force an allow-list or completely disable the thumbnailing system. The options for this
-are:
 
+### Storage Asset Transform
+The **Storage Asset Transform** can be used in conjunction with the
+presets to force an allow-list or completely disable the thumbnailing system.  
+The options for this are:
 -   **All** — Any valid thumbnail request will be returned
 -   **None** — No thumbnails will be returned, not even presets
 -   **Presets Only** — Only valid Storage Asset Presets will be returned
-:::
-<!-- prettier-ignore-end -->
+
 
 ## Requesting a Thumbnail
 
@@ -97,7 +95,7 @@ dimensions and adding "letterboxing" as needed.
 | ![Cover](../assets/200-200-cover-75.jpg)<br>_8KB • 200x200_ | ![Contain](../assets/200-200-contain-75.jpg)<br>_6KB • 200x133_ |
 
 <!-- prettier-ignore-start -->
-::: Aspect Ratio
+::: tip Aspect Ratio
 Images are never stretched or distorted even when changing the aspect ratio.
 :::
 <!-- prettier-ignore-end -->

docs/guides/presets.md

@@ -26,7 +26,7 @@ including: the full-text search query, any advanced filters added, sort field, s
 all other specific layout options.
 
 <!-- prettier-ignore-start -->
-::: Defaults vs Bookmarks
+::: tip Defaults vs Bookmarks
 It's important to be aware of the difference between a collection's
 _defaults_ and its _bookmarks_, both of which are configured by presets. A _default_ is how a user
 will initially view the collection detail without any further customization, while a _bookmark_ is a
@@ -35,14 +35,14 @@ named dataset that can be recalled at any point via the [collection navigation](
 <!-- prettier-ignore-end -->
 
 <!-- prettier-ignore-start -->
-::: System Defaults
+::: tip System Defaults
 You can also adjust the defaults and bookmarks for the Directus Activity,
 Directus Files, and Directus Users collections.
 :::
 <!-- prettier-ignore-end -->
 
 <!-- prettier-ignore-start -->
-::: Order of Defaults
+::: tip Order of Defaults
 Multiple defaults can be configured for a user, either for different layouts
 of even the same layout. In this case, the preset priority is: User, then Role, then Global.
 :::
@@ -55,7 +55,7 @@ of even the same layout. In this case, the preset priority is: User, then Role,
 3. Confirm this decision by clicking **Delete** in the dialog
 
 <!-- prettier-ignore-start -->
-:::danger Irreversible Change 
+::: danger Irreversible Change 
 This action is permanent and can not be undone. Please proceed with
 caution.
 :::

docs/guides/users.md

@@ -33,7 +33,7 @@ password and enable their account.
 3. Complete any of the [User Fields](/concepts/app-overview.md#user-detail)
 
 <!-- prettier-ignore-start -->
-::: User Preferences
+::: warning User Preferences
 This section of the User Detail is only visible/editable by the current user,
 and admins.
 :::

docs/readme.md

@@ -4,7 +4,8 @@ Welcome to the Directus documentation.
 
 ## Getting Started
 
-Novice Oriented. For a platform introduction and installation.
+Novice Oriented.   
+For a platform introduction and installation.
 
 -   [Introduction](/getting-started/introduction)
 -   [Support](/getting-started/support)
@@ -13,7 +14,8 @@ Novice Oriented. For a platform introduction and installation.
 
 ## Concepts
 
-Learning Oriented. For understanding the platform.
+Learning Oriented.  
+For understanding the platform.
 
 -   [Platform Overview](/concepts/platform-overview)
 -   [App Overview](/concepts/app-overview)
@@ -26,7 +28,8 @@ Learning Oriented. For understanding the platform.
 
 ## Guides
 
-Problem Oriented. Follow along with steps while working.
+Problem Oriented.  
+Follow along with steps while working.
 
 -   [Collections](/guides/collections)
 -   [Fields](/guides/fields)
@@ -39,7 +42,8 @@ Problem Oriented. Follow along with steps while working.
 
 ## Reference
 
-Information Oriented. Look up info and specificationss while working.
+Information Oriented.  
+Look up info and specifications while working.
 
 -   [Command Line Interface](/reference/command-line-interface)
 -   [Environment Variables](/reference/environment-variables)