5 files changed, 34 insertions, 5 deletions
diff --git a/packages/react-docs/CHANGELOG.json b/packages/react-docs/CHANGELOG.json
index d794e159b..f4af828d7 100644
--- a/packages/react-docs/CHANGELOG.json
+++ b/packages/react-docs/CHANGELOG.json
@@ -1,5 +1,14 @@
 [
     {
+        "version": "0.0.17",
+        "changes": [
+            {
+                "note": "Nest MD files under versions so that you can update them for future versions",
+                "pr": 844
+            }
+        ]
+    },
+    {
         "timestamp": 1531919263,
         "version": "0.0.16",
         "changes": [
diff --git a/packages/react-docs/package.json b/packages/react-docs/package.json
index 023c63db2..1ca0e0157 100644
--- a/packages/react-docs/package.json
+++ b/packages/react-docs/package.json
@@ -52,7 +52,8 @@
         "react-dom": "15.6.1",
         "react-markdown": "^3.2.2",
         "react-scroll": "^1.5.2",
-        "react-tooltip": "^3.2.7"
+        "react-tooltip": "^3.2.7",
+        "semver": "5.5.0"
     },
     "publishConfig": {
         "access": "public"
diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx
index a4e6f4f6e..ff33220d2 100644
--- a/packages/react-docs/src/components/documentation.tsx
+++ b/packages/react-docs/src/components/documentation.tsx
@@ -12,6 +12,7 @@ import {
 import * as _ from 'lodash';
 import CircularProgress from 'material-ui/CircularProgress';
 import * as React from 'react';
+import * as semver from 'semver';
 
 import { DocsInfo } from '../docs_info';
 import {
@@ -180,7 +181,20 @@ export class Documentation extends React.Component<DocumentationProps, Documenta
         return renderedSections;
     }
     private _renderSection(typeDefinitionByName: TypeDefinitionByName, sectionName: string): React.ReactNode {
-        const markdownFileIfExists = this.props.docsInfo.sectionNameToMarkdown[sectionName];
+        const markdownVersions = _.keys(this.props.docsInfo.sectionNameToMarkdownByVersion);
+        const eligibleVersions = _.filter(markdownVersions, mdVersion => {
+            return semver.lte(mdVersion, this.props.selectedVersion);
+        });
+        if (_.isEmpty(eligibleVersions)) {
+            throw new Error(
+                `No eligible markdown sections found for ${this.props.docsInfo.displayName} version ${
+                    this.props.selectedVersion
+                }.`,
+            );
+        }
+        const sortedEligibleVersions = eligibleVersions.sort(semver.rcompare.bind(semver));
+        const closestVersion = sortedEligibleVersions[0];
+        const markdownFileIfExists = this.props.docsInfo.sectionNameToMarkdownByVersion[closestVersion][sectionName];
         if (!_.isUndefined(markdownFileIfExists)) {
             return (
                 <MarkdownSection
diff --git a/packages/react-docs/src/docs_info.ts b/packages/react-docs/src/docs_info.ts
index 5d46dbda6..b37942da6 100644
--- a/packages/react-docs/src/docs_info.ts
+++ b/packages/react-docs/src/docs_info.ts
@@ -9,6 +9,7 @@ import {
     DocsInfoTypeConfigs,
     DocsMenu,
     DoxityDocObj,
+    SectionNameToMarkdownByVersion,
     SectionsMap,
     SupportedDocJson,
     TypeDefinitionByName,
@@ -24,7 +25,7 @@ export class DocsInfo {
     public packageUrl: string;
     public menu: DocsMenu;
     public sections: SectionsMap;
-    public sectionNameToMarkdown: { [sectionName: string]: string };
+    public sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion;
     public contractsByVersionByNetworkId?: ContractsByVersionByNetworkId;
     public typeConfigs: DocsInfoTypeConfigs;
     private readonly _docsInfo: DocsInfoConfig;
@@ -34,7 +35,7 @@ export class DocsInfo {
         this.displayName = config.displayName;
         this.packageUrl = config.packageUrl;
         this.sections = config.sections;
-        this.sectionNameToMarkdown = config.sectionNameToMarkdown;
+        this.sectionNameToMarkdownByVersion = config.sectionNameToMarkdownByVersion;
         this.contractsByVersionByNetworkId = config.contractsByVersionByNetworkId;
         this.typeConfigs = config.typeConfigs;
         this._docsInfo = config;
diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts
index f4e61edc9..cbc774c2e 100644
--- a/packages/react-docs/src/types.ts
+++ b/packages/react-docs/src/types.ts
@@ -1,3 +1,7 @@
+export interface SectionNameToMarkdownByVersion {
+    [version: string]: { [sectionName: string]: string };
+}
+
 export interface DocsInfoConfig {
     id: string;
     type: SupportedDocJson;
@@ -5,7 +9,7 @@ export interface DocsInfoConfig {
     packageUrl: string;
     menu: DocsMenu;
     sections: SectionsMap;
-    sectionNameToMarkdown: { [sectionName: string]: string };
+    sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion;
     visibleConstructors: string[];
     sectionNameToModulePath?: { [sectionName: string]: string[] };
     menuSubsectionToVersionWhenIntroduced?: { [sectionName: string]: string };