diff --git a/__tests__/__fixtures__/slug-docs/new-doc-slug.md b/__tests__/__fixtures__/slug-docs/new-doc-slug.md
new file mode 100644
index 000000000..336e0eaaf
--- /dev/null
+++ b/__tests__/__fixtures__/slug-docs/new-doc-slug.md
@@ -0,0 +1,7 @@
+---
+category: CATEGORY_ID
+title: This is the document title
+slug: marc-actually-wrote-a-test
+---
+
+Body
diff --git a/__tests__/cmds/docs.test.js b/__tests__/cmds/docs.test.js
index 32a659097..594ced066 100644
--- a/__tests__/cmds/docs.test.js
+++ b/__tests__/cmds/docs.test.js
@@ -277,6 +277,40 @@ describe('rdme docs', () => {
       });
     });
   });
+
+  describe('slug metadata', () => {
+    it('should use provided slug', () => {
+      const slug = 'new-doc-slug';
+      const doc = frontMatter(fs.readFileSync(path.join(fixturesDir, `/slug-docs/${slug}.md`)));
+      const hash = hashFileContents(fs.readFileSync(path.join(fixturesDir, `/slug-docs/${slug}.md`)));
+
+      const getMock = getNockWithVersionHeader(version)
+        .get(`/api/v1/docs/${doc.data.slug}`)
+        .basicAuth({ user: key })
+        .reply(404, {
+          error: 'DOC_NOTFOUND',
+          message: `The doc with the slug '${slug}' couldn't be found`,
+          suggestion: '...a suggestion to resolve the issue...',
+          help: 'If you need help, email support@readme.io and mention log "fake-metrics-uuid".',
+        });
+
+      const postMock = getNockWithVersionHeader(version)
+        .post(`/api/v1/docs`, { slug, body: doc.content, ...doc.data, lastUpdatedHash: hash })
+        .basicAuth({ user: key })
+        .reply(201, { slug: doc.data.slug, body: doc.content, ...doc.data, lastUpdatedHash: hash });
+
+      const versionMock = nock(config.host)
+        .get(`/api/v1/version/${version}`)
+        .basicAuth({ user: key })
+        .reply(200, { version });
+
+      return docs.run({ folder: './__tests__/__fixtures__/slug-docs', key, version }).then(() => {
+        getMock.done();
+        postMock.done();
+        versionMock.done();
+      });
+    });
+  });
 });
 
 describe('rdme docs:edit', () => {
diff --git a/src/cmds/docs/index.js b/src/cmds/docs/index.js
index da9704ef0..52daab7ef 100644
--- a/src/cmds/docs/index.js
+++ b/src/cmds/docs/index.js
@@ -116,7 +116,7 @@ exports.run = async function (opts) {
       const matter = frontMatter(file);
 
       // Stripping the subdirectories and markdown extension from the filename and lowercasing to get the default slug.
-      const slug = path.basename(filename).replace(path.extname(filename), '').toLowerCase();
+      const slug = matter.data.slug || path.basename(filename).replace(path.extname(filename), '').toLowerCase();
       const hash = crypto.createHash('sha1').update(file).digest('hex');
 
       return fetch(`${config.host}/api/v1/docs/${slug}`, {