如何使用 VuePress 构建系统文档

创建良好的文档对于公司构建的每个产品都至关重要，因为它的用户可以解决他们可能遇到的特定问题。系统文档可确保用户不断返回以参考文档，并且在尝试使用您的文档站点时不会感到沮丧。

VuePress 是一个静态站点生成器，它解析 Markdown 文件并将它们预呈现为客户端的 HTML 文件。 VuePress 的创建是为了简化文档站点的开发，为开源贡献者和开发者社区提供巨大的价值。

在本文中，您将学习如何使用由 VuePress 提供支持的现有开源项目创建文档指南，该技术随 Vue、Vue Router 和 Webpack 一起提供。

演示

检查此GitHub 存储库中的完整源代码。 Fork 并运行代码供您参考。

系统文档站点的现场演示。

先决条件

如果您想完成本指南，您将需要：

• Node>10+和yarn安装在你的本地机器上

  
  

设置项目

在本节中，您将创建一个新的 VuePress 项目来帮助制作系统文档指南。

运行以下命令：

 yarn create vuepress-site [optionalDirectoryName]

[optionalDirectoryName] ，将其替换为您想要的项目名称。

上面的命令搭建了项目文件和文件夹，并提示您配置 VuePress 站点的选项，它应该如下所示：

设置完成后，通过安装其依赖项导航到包含文档站点的docs/folder ，并使用以下命令启动开发服务器：

 cd docs/ yarn install yarn dev

VuePress 带有热重载功能，在开发过程中每次发生更改时都会更新站点，默认情况下可以在http://localhost:8080上访问它。

创建系统文档

主页是任何网站的第一页。这是一个向访问者展示你所关注的片段的机会——第一印象很重要。

在 docs 目录下的src文件夹中，使用以下 YAML 前端内容更新index.md文件：

 <!-- docs/src/index.md --> --- home: true heroImage: img/technical_writing_logo.png tagline: Technical writing is a form of communication that helps users solve problems with technology. As a technical writer, sharing your knowledge and experience with people helps you affirm that you have a solid understanding of the technology you're writing about. actionText: Get Started → actionLink: /guide/ --- ::: slot footer MIT Licensed | Copyright © 2022 [Teri Eyenike](https://twitter.com/terieyenike) :::

根 Markdown 文件中的上述前面事项执行以下操作：

• home: true : 验证网站首页是否显示
• 它指示image 、 tagline和号召性用语文本指向页面其余部分的入门/guide/ 。
• 显示footer文本信息

对于静态媒体资产，例如上面的heroImage ，在.vuepress目录中创建一个public文件夹， public文件夹中的另一个名为img的文件夹用于保存图像文件。公共文件夹将处理和引用页面上的所有资产，并将它们复制到各自文件的根目录。

接下来，让我们更新docs/src/.vuepress/config.js文件中的结构。

复制并粘贴这段代码：

 // docs/src/.vuepress/config.js const { description } = require('../../package'); module.exports = { title: 'Technical writing resources', description: description, themeConfig: { searchPlaceholder: 'Search...', nav: [ { text: 'Guide', link: '/guide/', }, { text: 'GitHub', link: 'https://github.com/dharmelolar/technical-writing-resources/', }, ], sidebar: { '/guide/': [ { title: 'Guide', collapsable: false, children: [ '', 'articles', 'books', 'courses', 'youtube', 'communities', 'tools', 'who-pay', 'open-source', 'open-projects.md', 'blogs', 'interviews', 'publication', 'job-boards', ], }, ], }, }, };

首先，您指定网站的title和description ，这有利于 SEO，由 Google 使用这些属性集进行索引。与元描述类似，从docs文件夹中的 package.json 文件引用的description是搜索引擎结果页面上显示的内容。

在themeConfig对象中，config.js文件中设置的参数如下：

• 要创建导航栏，您需要生成一个对象的nav数组，其中包含文本和到每个nav元素的路线
• sidebar ：一组链接，充当在侧边栏对象中设置的页面之间的导航

创建指南页面

本节中的guide页面将包含指向config.js文件中设置的支持链接的特定信息。

现在，让我们在docs/src文件夹中创建一个名为guide的文件夹，其中包含以下文件：

在 README.md 文件中，复制并粘贴以下内容：

 <!-- docs/src/guide/README.md --> # What is Technical Writing? Technical writing is a type of writing where the author is writing about a particularsubject that requires direction, instruction, or explanation. This style of writing has a very different purpose and different characteristics than other writing styles. ~ [YourDictionary](https://grammar.yourdictionary.com/word-definitions/definition-of-technical-writing.html) ## Resources This repository contains different technical writing resources that has been gatheredfrom all around the internet

注意：在 VuePress 中，每个子目录中包含的每个README.md或index.md文件都会自动转换为index.html及其对应的 URL / 。

对于其余的单个 Markdown 文件，请使用以下内容更新guide文件夹中的文件：

 <!-- docs/src/guide/articles.md --> # Articles - [How to Get Started with Technical Writing](https://www.samjulien.com/how-to-get-started-with-technical-writing) - [How to become a technical writer](https://www.freecodecamp.org/news/how-to-become-a-technical-writer/) - [Technical Writing for Beginners – An AZ Guide to Tech Blogging Basics](https://www.freecodecamp.org/news/technical-writing-for-beginners/) - [Technical Writing: What and How?](https://edidiongasikpo.com/technical-writing-what-and-how) - [How to Learn Technical Writing for Free](https://medium.com/technical-writing-is-easy/how-to-learn-technical-writing-for-free-c16d191b3cee) - [Getting Started with Technical Writing](https://dillionmegida.com/p/getting-started-with-technical-writing/) - [Advice for Technical Writing](https://css-tricks.com/advice-for-technical-writing/) - [How To Write Content That Readers Will Read Based On Learnings From User Psychology](https://www.everythingtechnicalwriting.com/how-to-write-content-that-readers-will-read/) - [How To Create A Technical Writing Portfolio](https://www.everythingtechnicalwriting.com/technical-writing-portfolio/) - [Writing Tips for Software Developers – How to Become a Better Tech Writer](https://www.freecodecamp.org/news/writing-tips-software-developers/) - [11 Best Practices for Writing API Documentation](https://treblle.com/blog/11-best-practices-for-writing-api-documentation) - [Technical Writing vs Technical Blogging](https://lo-victoria.com/what-you-need-to-know-about-technical-writing-vs-technical-blogging#cknj3ppa30d7m2ks14c8o0vnf)

 <!-- docs/src/guide/blogs.md --> # Blogs to follow for awesome writing contents | Technical Writers | Blogs | Twitter Handle | | :---------------- | ------------------------------------------ | ------------------------------------------------------- | | Damilola Ezekiel | https://dharmelolar.hashnode.dev | [@that_yhemmygirl](https://twitter.com/that_yhemmygirl) | | Tom Johnson | https://idratherbewriting.com/ | [@tomjohnson](https://twitter.com/tomjohnson) | | Kesi Parker | https://medium.com/@kesiparker | [@ParkerKesi](https://twitter.com/ParkerKesi) | | Tania Rascia | https://tania.dev/ | [@taniarascia](https://twitter.com/taniarascia) | | Dillion Megida | https://writing.dillionmegida.com/ | [@iamdillion](https://twitter.com/iamdillion) | | Linda Ikechukwu | https://www.everythingtechnicalwriting.com | [\_MsLinda](https://twitter.com/_MsLinda) | | Amruta Ranade | https://dev.to/amrutaranade | [@AmrutaRanade](https://twitter.com/AmrutaRanade) |

 <!-- docs/src/guide/books.md --> # Books - [Writing Well](https://www.julian.com/guide/write/intro) ~ Julian Shapiro - [Technical Writing, Simplified](https://www.amazon.com/Technical-Writing-Simplified-Nell-Johnson/dp/154326848X/ref=sr_1_1?crid=NUEHTLJWKLMN&keywords=Technical+Writing%2C+Simplified&qid=1651614066&s=books&sprefix=technical+writing%2C+simplified%2Cstripbooks-intl-ship%2C416&sr=1-1) ~ Nell Johnson - [Writing for Sotware Developers](https://philipkiely.gumroad.com/l/uZPZU) ~ Philip Kiely - [Technical Writing For Dummies](https://www.amazon.com/Technical-Writing-Dummies-Sheryl-Lindsell-Roberts/dp/0764553089) ~ Sheryl Lindsell-Roberts - [Docs for Developers: An Engineer's Field Guide to Technical Writing](https://www.amazon.com/Docs-Developers-Engineers-Technical-Writing/dp/1484272161/) ~ Jared Bhatti - [Modern Technical Writing: An Introduction to Software Documentation ](https://www.amazon.com/Modern-Technical-Writing-Introduction-Documentation-ebook/dp/B01A2QL9SS/ref=sr_1_1?crid=Y7S35M7LVXWE&dchild=1&keywords=modern+technical+writing&qid=1595414707&sprefix=modern+technical+%2Caps%2C346&sr=8-1) ~ Andrew Etter - [Everybody Writes: Your Go-To Guide to Creating Ridiculously Good Content](https://www.amazon.com/gp/product/1118905555/ref=as_li_tl?ie=UTF8&tag=techlife09-20&camp=1789&creative=9325&linkCode=as2&creativeASIN=1118905555&linkId=5a9769d7dc1a62419abb83e6b451ac96) ~ Ann Handley - [On Writing Well](https://www.amazon.com/gp/product/0060891548/ref=as_li_tl?ie=UTF8&tag=techlife09-20&camp=1789&creative=9325&linkCode=as2&creativeASIN=0060891548&linkId=27bd72a8da3fb242b39dbe4edb470daf) ~ William Zinsser - [Technical Communication](https://www.amazon.com/Technical-Communication-Mike-Markel-dp-1319245005/dp/1319245005/ref=dp_ob_image_bk) ~ Mike Markel

 <!-- docs/src/guide/communities.md --> # Communities Communities can provide valuable learning opportunities, growth, mentorship and career advancement. Connecting with people of similar interest is one of the reasons why people join communities. Here are some of the communities that technical writers can join: - [Write the Docs](https://www.writethedocs.org/) - [Linkedin Technical Writing Community](https://www.linkedin.com/groups/13705342/) - [Global Writers Community](https://web.facebook.com/groups/technicalwriterjobs/?_rdc=1&_rdr) - [API Documentation Group](https://www.linkedin.com/groups/3709151/) - [Technical Writer Forum](https://www.linkedin.com/groups/112571/) - [Hashnode](https://discord.com/invite/hashnode) - [The Good Docs Project Community](https://thegooddocsproject.dev/community/) - [Techwriters.dev](https://techwriters.dev/) - [r/technicalwriting](https://www.reddit.com/r/technicalwriting/)

 <!-- docs/src/guide/courses.md --> # Courses - [Technical Writing Courses for Engineers](https://developers.google.com/tech-writing) - [Technical Writing: How to Write Software Documentation](https://www.udemy.com/course/start-your-career-as-user-assistance-developer/) - [Learn API Technical Writing: JSON and XML for Writers](https://www.udemy.com/course/api-documentation-1-json-and-xml/) - [The Art of API Documentation](https://www.udemy.com/course/the-art-of-api-documentation/) - [Documenting APIs: A guide for technical writers and engineers](https://idratherbewriting.com/learnapidoc/) - [Technical Writer Certification Course](https://technicalwriter.teachable.com/p/technical-writing-certification) ~ Technical Writer Certification Course was created for aspiring technical writers or people who want to brush up on their technical writing skills. - [SEO FOR DEVS](https://seofordevs.com/) ~ SEO FOR DEVS is a free 2 weeks course that helps people discover your tech blog or side project in a systematic way - [API Documentation for Developers](https://apidocsfordevs.com/) ~ A hands-on guide to creating and maintaining API documentation.

 <!-- docs/src/guide/interviews.md --> # Preparing for technical writing interviews There are several tips that can help you land an interview but some of the important ones are having a well tailored resume and cover letters. Check out these cover letter templates and tips to help you land your next interview: - [Cover Letter Template for your next job ](https://dillionmegida.com/p/cover-letter-template/) - [How to Write an Enticing Cover Letter](https://ruthikegah.xyz/how-to-write-an-enticing-cover-letter) - [How to Write a Technical Writer Resume [+Examples]](https://technicalwriterhq.com/technical-writer-resume/) - [Best Technical Writer Cover Letter Example and Format ](https://technicalwriterhq.com/technical-writer-cover-letter/) Here are some resources to technical writing interview questions to help you prepare for your next interview. - [12 Technical Writer Interview Questions and Answers](https://technicalwriterhq.com/technical-writer-interview-questions/) - [Google Technical Writer Interview Questions](https://technicalwriterhq.com/google-technical-writer-interview-questions/) - [Technical Writing Job Interview](https://www.youtube.com/watch?v=cqaEgMv2JAg)

 <!-- docs/src/guide/job-boards.md --> # Job Boards For Technical Writing roles - [Startup.jobs](https://startup.jobs/?q=Technical+writer&remote=true&utm_campaign=Everything+Technical+Writing+Newsletter&utm_medium=email&utm_source=Revue+newsletter) - [Angel.co](https://angel.co/jobs) - [Content Writing Jobs](https://contentwritingjobs.com/)

 <!-- docs/src/guide/open-projects.md --> # Open Source Projects/Programs Technical Writers Can Contribute To - [Codecademy Docs](https://www.codecademy.com/resources/docs) ~ Docs is a community-driven collection of code documentation for popular programming languages and frameworks. - [The Good Docs Project](https://thegooddocsproject.dev/) ~ The Good Docs Project is a community working together to create the templates, tools, and resources to improve the overall quality of documentation in OSS and beyond. - [Google Season of Docs](https://developers.google.com/season-of-docs) ~ Season of Docs provides support for open source projects to improve their documentation and gives professional technical writers an opportunity to gain experience in open source. - [Hacktoberfest](https://hacktoberfest.digitalocean.com/) ~ Hacktoberfest is a yearly event to encourage people to contribute to open source in October. - [The GNOME Documentation Project](https://wiki.gnome.org/DocumentationProject)

 <!-- docs/src/guide/open-source.md --> # Open Source Projects Contributing to open source can be a rewarding way to learn, teach, and build experience in just about any skill you can imagine. A lot of peole contribute to open source for different reasons and the vital one which is improving one's skillset. Here are some articles to help you understand how to contribute to open source projects. - [The Technical Writers Guide to Contributing to Open Source Projects](https://edidiongasikpo.com/the-technical-writers-guide-to-contributing-to-open-source-projects) - [How to Contribute to Open-Source as a Technical Writer](https://javascript.plainenglish.io/how-to-contribute-to-open-source-as-a-technical-writer-bb708245480c) - [4 tips to becoming a technical writer with open source contributions](https://opensource.com/article/21/11/technical-writing-open-source) - [Getting started with Open Source as a Technical Writer](https://amara.hashnode.dev/getting-started-with-open-source-as-a-technical-writer)

 <!-- docs/src/guide/publication.md --> # Sites to publish articles - [Hashnode](https://hashnode.com/) ~ Hashnode is a free developer blogging platform to help you share your ideas with people in tech, developers, and engineers. - [Medium](https://medium.com/) ~ Medium is a social publishing platform with lots of users and you can publish diverse contents and ideas. - [Dev.to](https://dev.to/) ~ Dev.to is where programmers share ideas and help each other grow. It is an online community for sharing and discovering great ideas. - [Mirror.xyz](https://mirror.xyz/) ~ Mirror.xyz is a publishing platform for writers that leverages cryptocurrency and blockchain technology. - [Freecodecamp](https://www.freecodecamp.org/news/how-to-write-for-freecodecamp/) ~ FreeCodeCamp is a non-profit organization that consists of an interactive learning web platform, an online community forum, chat rooms, online publications and local organizations that intend to make learning web development accessible to anyone.

 <!-- docs/src/guide/tools.md --> # Tools - [Canva](https://www.canva.com/) ~ Canva is a graphic design platform, used to create social media graphics, presentations, posters, documents and other visual content. - [Removebg](https://www.remove.bg/) ~ A tools that is used to remove image backgrounds. - [Markdown](https://daringfireball.net/projects/markdown/) ~ Markdown is a text-to-HTML conversion tool for web writers. - [AsciiDoc](https://asciidoc.org/) ~ AsciiDoc is a lightweight and semantic markup language primarily designed for writing technical documentation. - [Denigma](https://denigma.app/) ~ Denigma is a tool that explains code in understandable english. - [Grammarly](https://app.grammarly.com/) ~ Grammarly is a typing assistant that reviews spelling, grammar, punctuation, clarity, engagement, and delivery mistakes. - [Hemingway App ](https://hemingwayapp.com/) ~ The Hemingway App is a web and desktop app that can improve your writing style and touch up your content. - [Quillbot AI](https://quillbot.com/) ~ Quillbot AI is a multi-purpose writing tool that can assist in improving your writing style. Some of its products are Paraphraser, Grammar Checker, Plagiarism Checker, Co-Writer, Summarizer, Citation Generator, and Word Counter. - [Notion](https://www.notion.so/) ~ Notion is an all-in-one workspace for your notes, tasks, wikis, and databases. It is a tool you can use to organize your thoughts, projects, and information. - [Dropbox Paper](https://www.dropbox.com/paper) ~ Dropbox Paper is an online document workspace, where you can organize and display text, media, and files all in one place. - [GoFullPage - Full Page Screen Capture](https://chrome.google.com/webstore/detail/gofullpage-full-page-scre/fdpohaocaechififmbbbbbknoalclacl?hl=en) ~ A chrome extension taht allows you take full page screenshot of your current browser window. - [Carbon](https://carbon.now.sh/) ~ Carbon is the easiest way to create and share beautiful images of your source code. - [Isitwp](https://www.isitwp.com/headline-analyzer) ~ IsItWP Headline Analyzer tool helps you write headlines that drive traffic, shares and rank better in search results. - [Capitalize my title](https://capitalizemytitle.com/) ~ Making title capitalization easy for your writing - [Wordtune](https://www.wordtune.com/) ~ Wordtune turns text into concise, engaging, well-written messages. - [Headline Analyzer](https://coschedule.com/headline-analyzer) ~ Write Headlines That Drive Traffic, Shares, And Search Results. - [Title Generator](https://tweakyourbiz.com/title-generator) ~ Generate great titles for articles and blog posts. - [SEO writing assistant](https://www.semrush.com/swa/) ~ A smart writing editor that helps you optimize your copy for engagement and SEO. - [HackMD](https://hackmd.io/) ~ A collaborative markdown editor for sharing your articles and getting feedback from others. - [Copyscape](https://www.copyscape.com/) ~ Plagiarism checker - [MarkDoc](https://markdoc.io/) ~ A superset of Markdown for creating custom documentation websites. It was created by Stripe and made open source in May 2022. - [Wordtune](https://www.wordtune.com/) ~ Wordtune is an AI- powered writing companion that rephrases your sentences to say exactly what you mean through clear, compelling, and authentic writing.

 <!-- docs/src/guide/who-pay.md --> # Who pays technical writers Writing technical contents for organizations and publications is an excellent way to earn extra income. This way, you learn a lot, then share your knowledge and get paid. Check out these compiled list for organizations that pays technical writers. - [Community writer program](https://github.com/malgamves/CommunityWriterPrograms) - [Get Paid to Write for These 45+ Websites](https://blog.idrisolubisi.com/get-paid-to-write-for-these-45-websites) - [Publications That Pay You To Write Technical Articles](https://catalins.tech/websites-that-pay-you-to-write-technical-articles)

 <!-- docs/src/guide/youtube.md --> # Youtube - [DocToHelpTV](https://www.youtube.com/user/DocToHelpTV/videos) - [Technical Writer HQ](youtube.com/channel/UCjMnGjosWhBxYtumwhQLZmA/videos) - [Amruta Ranade](https://www.youtube.com/channel/UCKsaZMjb3lsLe5YtasDifuA) - [William Smith](https://www.youtube.com/watch?v=amKDhaIlyOc) - [How to become a Technical Writer | Skills & Career Growth](youtube.com/watch?v=8l2KJXIBpB0)

您的页面应如下所示：

结束的想法

在本教程中，您使用 VuePress 开发了一个系统文档指南，它为您最喜欢的开源项目提供了一个单页应用程序。使用 VuePress，您可以在更短的时间内构建快速且可扩展的应用程序。

学到更多

• VuePress 文档
• 在 VuePress 中使用导航栏