Grab bag of maintenance tasks

dbirks · Aug 18, 2020 · 1bbb9c5 · 1bbb9c5
1 parent 407098d
commit 1bbb9c5
Show file tree

Hide file tree

Showing 5 changed files with 70 additions and 41 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,7 +1,7 @@
 ## Description & motivation
 <!---
 Describe your changes, and why you're making them. Is this linked to an open
-issue, a Trello card, or another pull request? Link it here.
+issue, a pull request on dbt core, etc?
 -->
 
 ## To-do before merge
@@ -14,7 +14,15 @@ Include any notes about things that need to happen before this PR is merged, e.g
 
 ## Pre-release docs
 Is this change related to an unreleased version of dbt?
-- [ ] Yes
-- [ ] No (if you're not sure, it's probably "No")
+- [ ] Yes: please update the base branch to `next`
+- [ ] No: please ensure the base branch is `current`
+- [ ] Unsure: we'll let you know!
 
-If yes, please change the base branch of this PR to `next`
+## Checklist
+If you added new pages (delete if not applicable):
+- [ ] The page has been added to `website/sidebars.js`
+- [ ] The new page has a unique filename
+
+If you removed existing pages (delete if not applicable):
+- [ ] The page has been removed from `website/sidebars.js`
+- [ ] An entry has been added to `_redirects`
diff --git a/README.md b/README.md
@@ -1,14 +1,24 @@
-A [docusaurus](https://docusaurus.io/en/) site that powers [docs.getdbt.com](https://docs.getdbt.com/)
+A [docusaurus](https://docusaurus.io/en/) site that powers [docs.getdbt.com](https://docs.getdbt.com/).
 
-To run this yourself:
-1. `brew install node`
-2. Clone this repo
-3. `cd` into the `website` subdirectory
-4. `npm install`
-5. `npm start`
+## Branching
+
+There are two long-lived branches in this repo:
+- `current`: This branch is what is reflected at at [docs.getdbt.com](https://docs.getdbt.com/)
+- `next`: This branch represent the next release of dbt, and is deployed [next.docs.getdbt.com](https://next.docs.getdbt.com/)
 
+## Contributing
+We welcome contributions from community members to this repo:
+- **Fixes**: If you notice an error (there are likely many), use the `Edit this page` button at the bottom of each page to suggest a change. We recommend you contribute small changes directly from the GitHub interface.
+- **New documentation**: If you contributed code in [dbt-core](https://github.com/fishtown-analytics/dbt), we encourage you to also write the docs here!
+- **Refactors**: At this time, we are unable to support community members who wish to re-write sections of docs.getdbt.com. We hope to change this in the future!
+
+If you are contributing significant changes, it may be worth setting up the repo to run locally, as follows:
+1. Ensure node is installed: `brew install node`
+2. Clone this repo: `[email protected]:fishtown-analytics/dbt.git`
+3. `cd` into the `website` subdirectory
+4. Install the required node packages: `npm install`
+5. Build the website: `npm start`
+6. Before pushing your changes to a branch, check that all links work by using the `make build` script
 
-## Notes
-* When using markdown links, you can use file paths relative to the current file, or, relative to the `website/docs/` directory, e.g. `[my link text](faqs/available-configurations.md)`.
-    * For FAQs: use the file path relative to the `docs` directory (since it may have to be resolved from different paths).
-    * Otherwise: use the relative filepath (fewer changes required if we rename a directory)
+## Custom components
+Check out [docs.getdbt.com/styles](https://docs.getdbt.com/styles) for examples of different components that can be used in these docs.
diff --git a/website/docs/docs/supported-databases.md b/website/docs/docs/supported-databases.md
@@ -1,10 +1,8 @@
 ---
-title: "Supported Databases"
+title: "Supported databases"
 id: "supported-databases"
 ---
 
-## Supported databases
-
 dbt supports the following databases:
 
 These database plugins are supported by the core dbt maintainers.

diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -49,14 +49,14 @@ module.exports = {
   baseUrl: '/',
   favicon: '/img/favicon.ico',
   tagline: 'Your entire analytics engineering workflow',
-  title: 'dbt - Documentation',
+  title: 'docs.getdbt.com',
   url: SITE_URL,
 
   themeConfig: {
     disableDarkMode: true,
     sidebarCollapsible: true,
     image: '/img/avatar.png',
-    
+
     announcementBar: WARNING_BANNER,
 
     algolia: {

diff --git a/website/src/pages/styles.js b/website/src/pages/styles.js
@@ -41,9 +41,17 @@ function Styles() {
 \`\`\`
 `}</pre>
             <CodeBlock>
-\`\`\`
 [view the license](license)
+            </CodeBlock>
+            <br/>
+            <p>Use a backslash to escape linking:</p>
+<pre>{`
+\`\`\`yml
+description: "this is \\[an escaped link](docs.getdbt.com)"
 \`\`\`
+`}</pre>
+            <CodeBlock>
+description: "this is \[an escaped link](docs.getdbt.com)"
             </CodeBlock>
             </div>
             <div className='section' style={{marginTop: '40px'}}>
@@ -126,29 +134,34 @@ password: hunter2
             </div>
 
             <div className='section' style={{marginTop: '40px'}}>
-                <h1>Link</h1>
-<pre>{`
-    Links to .md pages can be specified using:
-        - The absolute path to the document (docs/guides/best-practices)
-        - The "slug" of the document (best-practices)
-        - A relative path to the document (guides/best-practices)
-
-      <Link href="viewpoint">A link to the viewpoint</Link>
-
-    Invalid links are underlined, and will raise an error if compiled:
-
-      <Link href="viewpoint-bad">A link to the viewpoint (that does not work)</Link>
-
-    Markdown links are wired up to this component, so you can do:
-
-      [A markdown link to the viewpoint](viewpoint)
-
+                <h1>Markdown Link</h1>
+Links to pages can be specified using:
+<li>Just the <code>id</code>¹ of the document, if the <code>id</code> is unique. Note: the <code>id</code> may be specified in the YAML front-matter of a document. If not, then it defaults to the filename.</li>
+<li>A relative <code>id</code> of the document. Note: this is required when two documents have the same <code>id</code>.</li>
+<li>Or, a path to the document (with <code>.md</code> file extension), relative to the <code>website/docs/</code> directory. Note: this is _required_ for pages where the <code>id</code> looks like a filename (e.g. <code>profiles.yml</code>)</li>
+<br/>
+Bad links will appear with red underlines when building locally, and will cause an error in a deploy preview.
+<br/>
+<pre>{`[link to unique id](supported-databases)
+[disambiguated link to duplicate id](dbt-cli/installation)
+[second disambiguated link to duplicate id](on-premises/installation)
+[file paths work too](dbt-cli/installation.md)
+[link to document where id looks like a filename](reference/profiles.yml.md)
+[a bad link](bad-link)
 `}</pre>
-                <Link href="viewpoint">A link to the viewpoint</Link>
+
+                <Link href="supported-databases">link to unique id</Link>
                 <br />
-                <Link href="viewpoint-bad" ignoreInvalid={true}>A link to the viewpoint (that does not work)</Link>
+                <Link href="dbt-cli/installation">disambiguated link to duplicate id</Link>
                 <br />
-                <Link href="viewpoint">A markdown link to the viewpoint</Link>
+                <Link href="on-premises/installation">second disambiguated link to duplicate id</Link>
+                <br />
+                <Link href="dbt-cli/installation.md">file paths work too</Link>
+                <br />
+                <Link href="docs/reference/profiles.yml.md">link to document where id looks like a file</Link>
+                <br />
+                <Link href="bad-link" ignoreInvalid={true}>a bad link</Link>
+
             </div>
 
             <div className='section' style={{marginTop: '40px'}}>