Feat: Added support for external links in sections (styleguidist#921)

* Added support for external links in sections
* Removed the skip functionality, changed external prop to href prop
* Removed leftover skip and external prop
* Renamed test for target attribute
* Reverted change to docs
* Update example sections config and fialing tests
* Use a unique string as Section key
* Reverted change to Sections component; apparently there are cases where you dont get section slug
* Reverted package-lock.json
* Revert Cookbook.md
* Properly unstage Cookbook
* The cookbook is changed by pre-commit hook
* Added test for the href prop
* Changed jsx to markdown syntax

Author: BTMPL

docs/Components.md

@@ -113,6 +113,8 @@ Each section consists of (all fields are optional):
 - `exampleMode` — Initial state of the code example tab, uses [exampleMode](Configuration.md#examplemode).
 - `usageMode` — Initial state of the props and methods tab, uses [usageMode](Configuration.md#usagemode).
 - `ignore` — string/array of globs that should not be included in the section.
+- `href` - an URL to navigate to instead of navigating to the section content
+- `external` - if set, the link will open in a new window
 
 Configuring a style guide with textual documentation section and a list of components would look like:
 
@@ -134,6 +136,11 @@ module.exports = {
         {
           name: 'Configuration',
           content: 'docs/configuration.md'
+        },
+        {
+          name: 'Live Demo',
+          external: true,
+          href: 'http://example.com'
         }
       ]
     },

docs/Cookbook.md

@@ -117,8 +117,9 @@ const icons = iconsContext.keys().reduce((icons, file) => {
 export default icons
 ```
 
-````jsx
+````markdown
 // IconGallery.md
+
 ```jsx noeditor
 const icons = require('./load-icons').default
 
@@ -130,7 +131,7 @@ const iconElements = Object.keys(icons).map(iconName => {
     </span>
   )
 })
-;<div>{iconElements}</div>
+<div>{iconElements}</div>
 ```
 ````
 

examples/sections/styleguide.config.js

@@ -25,6 +25,11 @@ module.exports = {
 						},
 					],
 				},
+				{
+					name: 'Online documentation',
+					href: 'https://github.com/styleguidist/react-styleguidist',
+					external: true,
+				},
 			],
 			sectionDepth: 2,
 		},

loaders/utils/__tests__/__snapshots__/getSections.spec.js.snap

@@ -9,7 +9,9 @@ Array [
     },
     "description": undefined,
     "exampleMode": "collapse",
+    "external": undefined,
     "filepath": "components/Button/Readme.md",
+    "href": undefined,
     "name": "Readme",
     "sectionDepth": 0,
     "sections": Array [],
@@ -89,7 +91,9 @@ Array [
     "content": undefined,
     "description": undefined,
     "exampleMode": "collapse",
+    "external": undefined,
     "filepath": undefined,
+    "href": undefined,
     "name": "Components",
     "sectionDepth": 0,
     "sections": Array [],
@@ -156,7 +160,9 @@ Array [
     "content": undefined,
     "description": undefined,
     "exampleMode": "collapse",
+    "external": undefined,
     "filepath": undefined,
+    "href": undefined,
     "name": "Ignore",
     "sectionDepth": 0,
     "sections": Array [],
@@ -240,7 +246,9 @@ Object {
   "content": undefined,
   "description": undefined,
   "exampleMode": "collapse",
+  "external": undefined,
   "filepath": undefined,
+  "href": undefined,
   "name": "Components",
   "sectionDepth": 0,
   "sections": Array [],
@@ -257,7 +265,9 @@ Object {
   },
   "description": undefined,
   "exampleMode": "collapse",
+  "external": undefined,
   "filepath": "components/Button/Readme.md",
+  "href": undefined,
   "name": "Readme",
   "sectionDepth": 0,
   "sections": Array [],
@@ -327,7 +337,9 @@ Object {
   "content": undefined,
   "description": undefined,
   "exampleMode": "collapse",
+  "external": undefined,
   "filepath": undefined,
+  "href": undefined,
   "name": "Ignore",
   "sectionDepth": 0,
   "sections": Array [],

loaders/utils/getSections.js

@@ -68,8 +68,10 @@ function processSection(section, config, parentDepth) {
 		slug: slugger.slug(section.name),
 		sections: getSections(section.sections || [], config, sectionDepth),
 		filepath: contentRelativePath,
+		href: section.href,
 		components: getSectionComponents(section, config),
 		content,
+		external: section.external,
 	};
 }
 

src/rsg-components/ComponentsList/ComponentsList.js

@@ -6,13 +6,15 @@ import getUrl from '../../utils/getUrl';
 function ComponentsList({ classes, items, useRouterLinks = false, useHashId, hashPath }) {
 	const mappedItems = items.map(item => ({
 		...item,
-		href: getUrl({
-			name: item.name,
-			slug: item.slug,
-			anchor: !useRouterLinks,
-			hashPath: useRouterLinks ? hashPath : false,
-			id: useRouterLinks ? useHashId : false,
-		}),
+		href: item.href
+			? item.href
+			: getUrl({
+					name: item.name,
+					slug: item.slug,
+					anchor: !useRouterLinks,
+					hashPath: useRouterLinks ? hashPath : false,
+					id: useRouterLinks ? useHashId : false,
+			  }),
 	}));
 	return <ComponentsListRenderer classes={classes} items={mappedItems} />;
 }

src/rsg-components/ComponentsList/ComponentsList.spec.js

@@ -20,6 +20,24 @@ it('should set the correct href for items', () => {
 	expect(actual).toMatchSnapshot();
 });
 
+it('if a custom href is provided, should use it instead of generating internal link', () => {
+	const components = [
+		{
+			visibleName: 'External example',
+			name: 'External example',
+			href: 'http://example.com',
+		},
+		{
+			visibleName: 'Input',
+			name: 'Input',
+			slug: 'input',
+		},
+	];
+
+	const actual = shallow(<ComponentsList items={components} classes={{}} />);
+	expect(actual).toMatchSnapshot();
+});
+
 it('should set a parameter on link when useHashId is activated', () => {
 	const components = [
 		{

src/rsg-components/ComponentsList/ComponentsListRenderer.js

@@ -42,12 +42,16 @@ export function ComponentsListRenderer({ classes, items }) {
 
 	return (
 		<ul className={classes.list}>
-			{items.map(({ heading, visibleName, href, content }) => (
+			{items.map(({ heading, visibleName, href, content, external }) => (
 				<li
 					className={cx(classes.item, (!content || !content.props.items.length) && classes.isChild)}
 					key={href}
 				>
-					<Link className={cx(heading && classes.heading)} href={href}>
+					<Link
+						className={cx(heading && classes.heading)}
+						href={href}
+						target={external ? '_blank' : undefined}
+					>
 						{visibleName}
 					</Link>
 					{content}

src/rsg-components/ComponentsList/__snapshots__/ComponentsList.spec.js.snap

@@ -1,5 +1,26 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`if a custom href is provided, should use it instead of generating internal link 1`] = `
+<Styled(ComponentsList)
+  classes={Object {}}
+  items={
+    Array [
+      Object {
+        "href": "http://example.com",
+        "name": "External example",
+        "visibleName": "External example",
+      },
+      Object {
+        "href": "blank#input",
+        "name": "Input",
+        "slug": "input",
+        "visibleName": "Input",
+      },
+    ]
+  }
+/>
+`;
+
 exports[`should ignore items without visibleName 1`] = `
 <ul>
   <li

src/rsg-components/Link/Link.spec.js

@@ -23,3 +23,13 @@ it('should compose passed class names', () => {
 
 	expect(actual.find('a').prop('className')).toBe('baseLinkClass customClass');
 });
+
+it('should properly pass the target attribute', () => {
+	const actual = shallow(
+		<LinkRenderer href={href} target="_blank" classes={{}}>
+			{children}
+		</LinkRenderer>
+	);
+
+	expect(actual.find('a').prop('target')).toBe('_blank');
+});

src/rsg-components/Sections/Sections.js

@@ -6,7 +6,9 @@ import SectionsRenderer from 'rsg-components/Sections/SectionsRenderer';
 export default function Sections({ sections, depth }) {
 	return (
 		<SectionsRenderer>
-			{sections.map((section, idx) => <Section key={idx} section={section} depth={depth} />)}
+			{sections
+				.filter(section => !section.href)
+				.map((section, idx) => <Section key={idx} section={section} depth={depth} />)}
 		</SectionsRenderer>
 	);
 }