If you want to keep your doc development simple, you can just edit Markdown files and let GitHub do the dirty work. GitHub Pages uses Jekyll behind the scenes to turn doc pages into full doc sites. Jekyll is a static site generator written in Ruby. GitHub’s docs recommend testing your site locally using Jekyll. They may also have trouble with links or templates. Unfortunately, while editor previews may help catch a few typos, they won’t test the full end result of static site generation and deployment. Even GitHub’s web editor lets you preview Markdown before committing it. Many IDEs have Markdown editors with preview panes. One way to test pages is to use a Markdown editor. However, I want a way to view the doc site in its fullness before committing any changes so I don’t accidentally publish any mistakes. As soon as changes are committed to that source, the updated pages go live. Unfortunately, I hit one challenge while trying GitHub Pages for the first time: How could I test the doc site before publishing it? A repository using GitHub Pages must be configured with a specific branch and folder ( / (root) or /docs) as the publishing source. GitHub Pages also provides free hosting with a decent domain name for the doc site. The docs will be version-controlled for safety and shared from a single source of truth. Docs can be written as Markdown files, Liquid templates, or raw assets like HTML and CSS. GitHub Pages are great because they make it easy to develop docs and code together as part of the same workflow without needing extra tools. I just found out about this cool feature myself! Your doc site will go live at: If this is new to you, then you can learn all about this cool feature from the GitHub docs here: Working with GitHub Pages. All you need to do is configure a publishing source for your repository. If you have a GitHub repository, did you know that you can create your own documentation site for it within GitHub? Using GitHub Pages, you can write your docs as a set of Markdown pages and then configure your repository to generate and publish a static web site for those pages. Reload the GitHub Pages site, and review the changes.Temporarily change the repository’s GitHub Pages publishing source to the new branch.Commit your doc changes to a new branch.TL DR: If you want to test your full GitHub Pages site before publishing but don’t want to set up Ruby and Jekyll on your local machine, then:
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |