Github pages docs

Github pages docs DEFAULT

You might be familiar with how GitHub Pages helps you share your work with the world or maybe you have attended a class that helped you build your first GitHub Pages site. Recent improvements to GitHub Pages have made it easier to publish your site from a variety of sources. One of these sources is your repository&#;s folder.

Quality documentation is a hallmark of any healthy software project. For open-source projects, however, maintaining a robust compendium of knowledge detailing all the ins and outs is paramount. Well-curated documentation increases your project&#;s approachability, provides asynchronous guidance, and fosters the type of uncoordinated collaboration that propels open-source software development.

Hosting your documentation on the web can present time-consuming challenges that make publishing and maintaining it an unrewarding experience — one that it&#;s often easy to avoid. Grappling with multiple disparate publishing tools like FTP servers and databases means files often exist in various states and multiple locations, all of which require manual synchronization. To be clear, conventional web publishing provides unparalleled flexibility and power; but it comes at the expense of simplicity and, in many cases, utility.

When it comes to documentation, a path with less resistance is often the better approach.

GitHub Pages gives you a direct path to create websites for your projects, which makes it a natural choice for publishing and maintaining documentation. Because GitHub Pages supports Jekyll, you can pen your documentation in plain text or Markdown to help maintain a lower barrier to contribution. Jekyll also includes support for many helpful tools like variables, templates, and automatic code highlighting, which gives you much of the flexibility you&#;d find in a bulkier platform without the added complexity.

Most importantly, using GitHub Pages means your documentation lives alongside your code on GitHub, where you can use things like Issues and Pull Requests to ensure it receives the high level of care it deserves; and because GitHub Pages lets you publish from the directory on the branch, you can maintain your codebase and its published documentation on the same branch.

Get started today

Publishing your first documentation page only takes a few minutes.

  1. Create a file on your repository&#;s branch.
  2. Add your content and any necessary Jekyll front matter, then commit your changes.

create-an-index-file

  1. Visit your repository&#;s settings tab and select as the GitHub Pages source. Click save, and you&#;re done.

GitHub Pages will read the contents of your directory, convert the into HTML, and publish the results at your GitHub Pages URL.

This will generate the most basic HTML output that you can further customize with templates, CSS, and other features available in Jekyll. To see examples of what all is possible, take a look at the GitHub Pages Showcase.

Sours: https://github.blog/publish-your-project-documentation-with-github-pages/

Websites for you and your projects.

GitHub Pages

Hosted directly from your GitHub repository. Just edit, push, and your changes are live.

Pages Help
Bootstrap

You get one site per GitHub account and organization,
and unlimited project sites. Let‘s get started.

  • Create a repository

    Head over to GitHub and create a new public repository named username.github.io, where username is your username (or organization name) on GitHub.

    If the first part of the repository doesn’t exactly match your username, it won’t work, so make sure to get it right.

  • What git client are you using?

  • Download GitHub Desktop

    GitHub Desktop is a great way to use Git and GitHub on macOS and Windows.

    Download GitHub DesktopGitHub Desktop screenshot
  • Clone the repository

    Go to the folder where you want to store your project, and clone the new repository:

    ~$git clone https://github.com/username/username.github.io

  • Clone the repository

    Click the "Set up in Desktop" button. When the GitHub desktop app opens, save the project.

    If the app doesn't open, launch it and clone the repository from the app.

  • Clone the repository

    After finishing the installation, head back to GitHub.com and refresh the page. Click the "Set up in Desktop" button. When the GitHub desktop app opens, save the project.

    If the app doesn't open, launch it and clone the repository from the app.

  • Hello World

    Enter the project folder and add an index.html file:

    ~$cd username.github.io

    ~$echo "Hello World" > index.html

  • Create an index file

    Grab your favorite text editor and add an index.html file to your project:

  • Push it

    Add, commit, and push your changes:

    ~$git add --all

    ~$git commit -m "Initial commit"

    ~$git push -u origin main

  • Commit & publish

    Enter the repository, commit your changes, and press the publish button.

    Demonstration of steps required to create the initial commit and publish the repository in GitHub Desktop
  • …and you're done!

    Fire up a browser and go to https://username.github.io.

  • Use a theme, or start from scratch?

    You have the option to start with one of the pre-built themes,
    or to create a site from scratch.

  • Repository Settings

    Head over to GitHub.com and create a new repository, or go to an existing one.
    Click on the Settings tab.

    Settings for a repository
  • Theme chooser

    Scroll down to the GitHub Pages section. Press Choose a theme.

    Automatic Generator button on GitHub.com, Settings
  • Pick a theme

    Choose one of the themes from the carousel at the top.
    When you're done, click Select theme on the right.

    Choose layout
  • Edit content

    Use the editor to add content to your site.

    Add content to your GitHub Pages site
  • Commit

    Enter a commit comment and click on Commit changes below the editor.

    Commit Markdown content to your repository
  • Create an index file

    Head over to GitHub.com and create a new repository, or go to an existing one.
    Click on the Create new file button.

    Create a file in your repository
  • Hello World

    Name the file and type some HTML content into the editor.

    Hello World on GitHub.com
  • Commit the file

    Scroll to the bottom of the page, write a commit message, and commit the new file.

    Commit the file
  • Repository Settings

    Click on the Settings tab and scroll down to the GitHub Pages section.
    Then select the main branch source and click on the Save button.

    GitHub Pages Source Setting
  • …and you're done!

    Fire up a browser and go to http://username.github.io/repository.

Sours: https://pages.github.com/
  1. Heath marshall
  2. Vba create list
  3. Nexus phone case
  4. Zillow holstein iowa

npm

Publish files to a branch on GitHub (or any other branch anywhere else).

Getting Started

npm install gh-pages --save-dev

This module requires Git .

Basic Usage

varghpages=require('gh-pages');ghpages.publish('dist',function(err){});

ghpages.publish(dir,callback);// orghpages.publish(dir,options,callback);

Calling this function will create a temporary clone of the current repository, create a branch if one doesn't already exist, copy over all files from the base path, or only those that match patterns from the optional configuration, commit all changes, and push to the remote.

If a branch already exists, it will be updated with all commits from the remote before adding any commits from the provided files.

Note that any files in the branch that are not in the files will be removed. See the option if you don't want any of the existing files removed.

The base directory for all source files (those listed in the config property).

Example use:

/** * Given the following directory structure: * * dist/ * index.html * js/ * site.js * * The usage below will create a `gh-pages` branch that looks like this: * * index.html * js/ * site.js * */ghpages.publish('dist',callback);

Options

The default options work for simple cases. The options described below let you push to alternate branches, customize your commit messages, and more.

options.src

  • type:
  • default:

The minimatch pattern or array of patterns used to select which files should be published.

options.branch

  • type:
  • default:

The name of the branch you'll be pushing to. The default uses GitHub's branch, but this can be configured to push to any branch on any remote.

Example use of the option:

/** * This task pushes to the `master` branch of the configured `repo`. */ghpages.publish('dist',{branch: 'master',repo: 'https://example.com/other/repo.git'},callback);

options.dest

  • type:
  • default:

The destination folder within the destination branch. By default, all files are published to the root of the repository.

Example use of the option:

/** * Place content in the static/project subdirectory of the target * branch. */ghpages.publish('dist',{dest: 'static/project'},callback);

options.dotfiles

  • type:
  • default:

Include dotfiles. By default, files starting with are ignored unless they are explicitly provided in the array. If you want to also include dotfiles that otherwise match your patterns, set in your options.

Example use of the option:

/** * The usage below will push dotfiles (directories and files) * that otherwise match the `src` pattern. */ghpages.publish('dist',{dotfiles: true},callback);

options.add

  • type:
  • default:

Only add, and never remove existing files. By default, existing files in the target branch are removed before adding the ones from your config. If you want the task to add new files but leave existing ones untouched, set in your options.

Example use of the option:

/** * The usage below will only add files to the `gh-pages` branch, never removing * any existing files (even if they don't exist in the `src` config). */ghpages.publish('dist',{add: true},callback);

options.repo

  • type:
  • default: url for the origin remote of the current dir (assumes a git repository)

By default, assumes that the current working directory is a git repository, and that you want to push changes to the remote.

If instead your script is not in a git repository, or if you want to push to another repository, you can provide the repository URL in the option.

Example use of the option:

/** * If the current directory is not a clone of the repository you want to work * with, set the URL for the repository in the `repo` option. This usage will * push all files in the `src` config to the `gh-pages` branch of the `repo`. */ghpages.publish('dist',{repo: 'https://example.com/other/repo.git'},callback);

options.remote

  • type:
  • default:

The name of the remote you'll be pushing to. The default is your remote, but this can be configured to push to any remote.

Example use of the option:

/** * This task pushes to the `gh-pages` branch of of your `upstream` remote. */ghpages.publish('dist',{remote: 'upstream'},callback);

options.tag

Create a tag after committing changes on the target branch. By default, no tag is created. To create a tag, provide the tag name as the option value.

options.message

  • type:
  • default:

The commit message for all commits.

Example use of the option:

/** * This adds commits with a custom message. */ghpages.publish('dist',{message: 'Auto-generated commit'},callback);

options.user

  • type:
  • default:

If you are running the task in a repository without a or git config properties (or on a machine without these global config properties), you must provide user info before git allows you to commit. The object accepts and string values to identify the committer.

Example use of the option:

ghpages.publish('dist',{user: {name: 'Joe Code',email: '[email protected]'}},callback);

options.remove

  • type:
  • default:

Removes files that match the given pattern (Ignored if used together with ). By default, removes everything inside the target branch auto-generated directory before copying the new files from .

Example use of the option:

ghpages.publish('dist',{remove: "*.json"},callback);

options.push

  • type:
  • default:

Push branch to remote. To commit only (with no push) set to .

Example use of the option:

ghpages.publish('dist',{push: false},callback);

options.history

  • type:
  • default:

Push force new commit without parent history.

Example use of the option:

ghpages.publish('dist',{history: false},callback);

options.silent

  • type:
  • default:

Avoid showing repository URLs or other information in errors.

Example use of the option:

/** * This configuration will avoid logging the GH_TOKEN if there is an error. */ghpages.publish('dist',{repo: 'https://'+process.env.GH_TOKEN+'@github.com/user/private-repo.git',silent: true},callback);

options.beforeAdd

  • type:
  • default:

Custom callback that is executed right before .

The CLI expects a file exporting the beforeAdd function

gh-pages --before-add ./cleanup.js

Example use of the option:

/** * beforeAdd makes most sense when `add` option is active * Assuming we want to keep everything on the gh-pages branch * but remove just `some-outdated-file.txt` */ghpages.publish('dist',{add: true,asyncbeforeAdd(git){returngit.rm('./some-outdated-file.txt');}},callback);

options.git

  • type:
  • default:

Your executable.

Example use of the option:

/** * If `git` is not on your path, provide the path as shown below. */ghpages.publish('dist',{git: '/path/to/git'},callback);

Command Line Utility

Installing the package creates a command line utility. Run to see a list of supported options.

With a local install of , you can set up a package script with something like the following:

"scripts": { "deploy": "gh-pages -d dist" }

And then to publish everything from your folder to your branch, you'd run this:

Debugging

To get additional output from the script, set . For example:

NODE_DEBUG=gh-pages npm run deploy

Dependencies

Note that this plugin requires Git or higher (because it uses the option for ). If you'd like to see this working with earlier versions of Git, please open an issue.

Test Status

Tips

when get error

The module writes temporary files to a directory. The location of this directory can be customized by setting the environment variable.

If fails, you may find that you need to manually clean up the cache directory. To remove the cache directory, run or remove .

Deploying to github pages with custom domain

Modify the deployment line to your deploy script if you use custom domain. This will prevent the deployment from removing the domain settings in GitHub.

Deploying with GitHub Actions

In order to deploy with GitHub Actions, you will need to define a user and set the git repository for the process. See the example step below

- name: Deploy with gh-pagesrun: | git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git npx gh-pages -d build -u "github-actions-bot <[email protected]>" env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The is provided automatically as part of the GitHub Action and does not require any further configuration, but simply needs to be passed in as an environmental variable to the step. is the owner and repository name and is also passed in automatically, but does not need to be added to the list.

See Issue # for more information

Deploying with GitHub Actions and a named script

If you are using a named script in the file to deploy, you will need to ensure you pass the variables properly to the wrapped script. Given the script below:

"scripts": { "deploy": "gh-pages -d build" }

You will need to utilize the option to pass any additional arguments:

- name: Deploy with gh-pagesrun: | git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git npm run deploy -- -u "github-actions-bot <[email protected]>"env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

See Pull Request # for more information.

Sours: https://www.npmjs.com/package/gh-pages
Criando uma página no Github Pages - Github

Deploying your docs

A basic guide to deploying your docs to various hosting providers


GitHub Pages

If you host the source code for a project on GitHub, you can easily use GitHub Pages to host the documentation for your project. There are two basic types of GitHub Pages sites: Project Pages sites, and User and Organization Pages sites. They are nearly identical but have some important differences, which require a different work flow when deploying.

Project Pages

Project Pages sites are simpler as the site files get deployed to a branch within the project repository ( by default). After you the primary working branch (usually ) of the git repository where you maintain the source documentation for your project, run the following command:

That's it! Behind the scenes, MkDocs will build your docs and use the ghp-import tool to commit them to the branch and push the branch to GitHub.

Use to get a full list of options available for the command.

Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the or commands and reviewing the built files locally.

Warning

You should never edit files in your pages repository by hand if you're using the command because you will lose your work the next time you run the command.

Organization and User Pages

User and Organization Pages sites are not tied to a specific project, and the site files are deployed to the branch in a dedicated repository named with the GitHub account name. Therefore, you need working copies of two repositories on our local system. For example, consider the following file structure:

After making and verifying updates to your project you need to change directories to the repository and call the command from there:

Note that you need to explicitly point to the configuration file as it is no longer in the current working directory. You also need to inform the deploy script to commit to the branch. You may override the default with the remote_branch configuration setting, but if you forget to change directories before running the deploy script, it will commit to the branch of your project, which you probably don't want.

Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the or commands and reviewing the built files locally.

Warning

You should never edit files in your pages repository by hand if you're using the command because you will lose your work the next time you run the command.

Custom Domains

GitHub Pages includes support for using a Custom Domain for your site. In addition to the steps documented by GitHub, you need to take one additional step so that MkDocs will work with your custom domain. You need to add a file to the root of your docs_dir. The file must contain a single bare domain or subdomain on a single line (see MkDocs' own CNAME file as an example). You may create the file manually, or use GitHub's web interface to set up the custom domain (under Settings / Custom Domain). If you use the web interface, GitHub will create the file for you and save it to the root of your "pages" branch. So that the file does not get removed the next time you deploy, you need to copy the file to your . With the file properly included in your , MkDocs will include the file in your built site and push it to your "pages" branch each time you run the command.

If you are having problems getting a custom domain to work, see GitHub's documentation on Troubleshooting custom domains.

Read the Docs

Read the Docs offers free documentation hosting. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. Read the Docs supports MkDocs out-of-the-box. Follow the instructions on their site to arrange the files in your repository properly, create an account and point it at your publicly hosted repository. If properly configured, your documentation will update each time you push commits to your public repository.

Note

To benefit from all of the features offered by Read the Docs, you will need to use the Read the Docs theme which ships with MkDocs. The various themes which may be referenced in Read the Docs' documentation are Sphinx specific themes and will not work with MkDocs.

Other Providers

Any hosting provider which can serve static files can be used to serve documentation generated by MkDocs. While it would be impossible to document how to upload the docs to every hosting provider out there, the following guidelines should provide some general assistance.

When you build your site (using the command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to ) in your config file. Generally, you will simply need to copy the contents of that directory to the root directory of your hosting provider's server. Depending on your hosting provider's setup, you may need to use a graphical or command line ftp, ssh or scp client to transfer the files.

For example, a typical set of commands from the command line might look something like this:

Of course, you will need to replace with the username you have with your hosting provider and with the appropriate domain name. Additionally, you will need to adjust the to match the configuration of your hosts' file system.

See your host's documentation for specifics. You will likely want to search their documentation for "ftp" or "uploading site".

Local Files

Rather than hosting your documentation on a server, you may instead distribute the files directly, which can then be viewed in a browser using the scheme.

Note that, due to the security settings of all modern browsers, some things will not work the same and some features may not work at all. In fact, a few settings will need to be customized in very specific ways.

  • site_url:

    The must be set to an empty string, which instructs MkDocs to build your site so that it will work with the scheme.

  • use_directory_urls:

    Set to . Otherwise, internal links between pages will not work properly.

  • search:

    You will need to either disable the search plugin, or use a third-party search plugin which is specifically designed to work with the scheme. To disable all plugins, set the setting to an empty list.

    If you have other plugins enabled, simply ensure that is not included in the list.

When writing your documentation, it is imperative that all internal links use relative URLs as documented. Remember, each reader of your documentation will be using a different device and the files will likely be in a different location on that device.

If you expect your documentation to be viewed off-line, you may also need to be careful about which themes you choose. Many themes make use of CDNs for various support files, which require a live Internet connection. You will need to choose a theme which includes all support files directly in the theme.

When you build your site (using the command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to ) in your config file. Generally, you will simply need to copy the contents of that directory and distribute it to your readers. Alternatively, you may choose to use a third party tool to convert the HTML files to some other documentation format.

Pages

When MkDocs builds the documentation it will include a html file in the build directory. This file will be automatically used when deploying to GitHub but only on a custom domain. Other web servers may be configured to use it but the feature won't always be available. See the documentation for your server of choice for more information.

Sours: https://www.mkdocs.org/user-guide/deploying-your-docs/

Pages docs github

Jekyll Jekyll Logo

 Improve this page

GitHub Pages are public web pages for users, organizations, and repositories, that are freely hosted on GitHub’s domain or on a custom domain name of your choice. GitHub Pages are powered by Jekyll behind the scenes, so they’re a great way to host your Jekyll-powered website for free.

Your site is automatically generated by GitHub Pages when you push your source files. Note that GitHub Pages works equally well for regular HTML content, simply because Jekyll treats files without front matter as static assets. So if you only need to push generated HTML, you’re good to go without any further setup.

The GitHub Pages Documentation is comprehensive and includes a a guide to setting up a GitHub Pages site using Jekyll. We recommend following this guide.

This page contains some additional information which may be useful when working on GitHub Pages sites with Jekyll.

GitHub Pages Documentation, Help, and Support

For more information about what you can do with GitHub Pages, as well as for troubleshooting guides, you should check out GitHub’s Pages Help section. If all else fails, you should contact GitHub Support.

Project Page URL Structure

Sometimes it’s nice to preview your Jekyll site before you push your branch to GitHub. The subdirectory-like URL structure GitHub uses for Project Pages complicates the proper resolution of URLs. In order to assure your site builds properly, use the handy URL filters:

This way you can preview your site locally from the site root on localhost, but when GitHub generates your pages from the branch all the URLs will resolve properly.

Deploying Jekyll to GitHub Pages

GitHub Pages work by looking at certain branches of repositories on GitHub. There are two basic types available: user/organization and project pages. The way to deploy these two types of sites are nearly identical, except for a few minor details.

User and Organization Pages

User and organization pages live in a special GitHub repository dedicated to only the GitHub Pages files. This repository must be named after the account name. For example, @mojombo’s user page repository has the name .

Content from the branch of your repository will be used to build and publish the GitHub Pages site, so make sure your Jekyll site is stored there.

Custom domains do not affect repository names

GitHub Pages are initially configured to live under the subdomain, which is why repositories must be named this way even if a custom domain is being used.

Project Pages

Unlike user and organization Pages, Project Pages are kept in the same repository as the project they are for, except that the website content is stored in a specially named branch or in a folder on the branch. The content will be rendered using Jekyll, and the output will become available under a subpath of your user pages subdomain, such as (unless a custom domain is specified).

The Jekyll project repository itself is a perfect example of this branch structure—the master branch contains the actual software project for Jekyll, and the Jekyll website that you’re looking at right now is contained in the docs folder of the same repository.

Please refer to GitHub official documentation on user, organization and project pages to see more detailed examples.

Source files must be in the root directory

GitHub Pages overrides the “Site Source” configuration value, so if you locate your files anywhere other than the root directory, your site may not build correctly.

Installing the gem on Windows

While Windows is not officially supported, it is possible to install the gem on Windows. Special instructions can be found on our Windows-specific docs page.

Sours: https://jekyllrb.com/docs/github-pages/
Create Your First GitHub Pages Website

Focus on writing good documentation

Just the Docs gives your documentation a jumpstart with a responsive Jekyll theme that is easily customizable and hosted on GitHub Pages.

Get started nowView it on GitHub


Getting started

Dependencies

Just the Docs is built for Jekyll, a static site generator. View the quick start guide for more information. Just the Docs requires no special plugins and can run on GitHub Pages’ standard Jekyll compiler. The Jekyll SEO Tag plugin is included by default (no need to run any special installation) to inject SEO and open graph metadata on docs pages. For information on how to configure SEO and open graph metadata visit the Jekyll SEO Tag usage guide.

Quick start: Use as a GitHub Pages remote theme

  1. Add Just the Docs to your Jekyll site’s as a remote theme

    You must have GitHub Pages enabled on your repo, one or more Markdown files, and a file. See an example repository

Local installation: Use the gem-based theme

  1. Install the Ruby Gem
  2. Add Just the Docs to your Jekyll site’s
  3. Optional: Initialize search data (creates )
  4. Run you local Jekyll server
  5. Point your web browser to http://localhost

If you’re hosting your site on GitHub Pages, set up GitHub Pages and Jekyll locally so that you can more easily work in your development environment.

Configure Just the Docs


About the project

Just the Docs is © by Patrick Marsceill.

License

Just the Docs is distributed by an MIT license.

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. Read more about becoming a contributor in our GitHub repo.

Thank you to the contributors of Just the Docs!

Code of Conduct

Just the Docs is committed to fostering a welcoming community.

View our Code of Conduct on our GitHub repository.


Back to top

Copyright © Patrick Marsceill. Distributed by an MIT license.

Edit this page on GitHub

Sours: https://pmarsceill.github.io/just-the-docs/

Similar news:

Publish your Markdown docs on GitHub Pages

As a developer you've most likely switched machines, even OS several times. Maybe you've performed a specific set of operations that you'll have to repeat in the future? want to remember some command lines? share code snippets? capture online course notes? 

For all of the reasons above, and many more, having a personal documentation website is ideal. It lets you organize and synthesize all the information that is relevant to YOU in your own personal way, with the added benefit of being easily shareable. 

What we'll do

A project containing all your Markdown files, hosted on Github Pages.

Requirements

How we do it

Install

We'll use as static site generator, so let's install it:

Create your docs source project

Now create the basic project structure, in your projects folder:

Replace GITHUB_USERNAME with your GitHub username or whatever you prefer to name your project. We'll be referencing it in the next steps and it will become clearer why you might want to choose that project name. 

Check the created files in that folder, you'll see something like the following:

Go ahead and try running then open http:// in your browser. And voilà! You have a personal documentation local website. Any  file added in will appear as a new web page. Try to edit for example.

contains your project configuration. You can customize your site name, navigation layout and so on. A simple example would be:

You can also use the readthedocs provided theme by adding the following:

For reference see https://www.mkdocs.org/user-guide/configuration/

At this point you should have something like this locally:
mkdocs generated website with readthedocs theme

For a local documentation project that would be enough. But we'll go ahead and make this deployable to your GitHub page.

Create the GitHub repositories

GitHub allows you to host a website in a specific repository matching GITHUB_USERNAME.github.io, with your actual GitHub username in place of GITHUB_USERNAME.

Luckily makes it easy to push your project build files to your GitHub page through the command.

The downside of is that it wipes out all the files in to generate the website files (html, css, js).

To overcome this constraint and simplify the deploy process you'll track your GitHub page repo, GITHUB_USERNAME.github.io, independently as a git submodule of your docs source project. Which will allow to run from within the docs source project itself.

Ultimately you'll need two distinct repositories: one for your GitHub page, another one for your source files.

Create the GitHub page repo

  • Go to https://github.com/new and create your GitHub page repository
  • Name it GITHUB_USERNAME.github.io (replace GITHUB_USERNAME with your actual GitHub username) image

Create the source repo

  • Go to https://github.com/new and create your source repository
  • Name it GITHUB_USERNAME (replace GITHUB_USERNAME with your actual GitHub username or anything else you chose to name the new project previously created) image

Note that a repository named as your username is a special repository on GitHub. Its will appear on your public profile. So you can customize that as well.

At this point you should have two GitHub repositories:

Git repoDescription
GITHUB_USERNAME.git (or anything else you chose to name it)Source repo with markdown files
GITHUB_USERNAME.github.io.gitGitHub page repo with static web files

Initialize the git repositories

Back in the folder created previously:

Then initialize the GitHub page repo:

You should now have two folders tracked in their respective GitHub repositories:

Now delete since there's no need for it to exist independently:

Add your GitHub page repo as a submodule of your source repo instead:

Deploy your docs to your GitHub page

Run:

Go ahead and open https://GITHUB_USERNAME.github.io in your browser. And voilà! Your very own personal documentation on your GitHub page.

Note that you might have to wait a few seconds for your changes to be deployed.

Add deploy command in Makefile

The command in itself isn't very user friendly nor easy to remember so we'll add a simple to make (word choice on purpose) it easier to deploy changes.

Create a in your source folder with the following:

Ensure to paste indentation as Tabs or else you might get an error in the lines of

Now you can simply run whenever you want to publish something.

Keep both repositories in sync

You might also want to update latest commit version of your GitHub page submodule whenever a deploy is performed. Not technically required, but good for tracking purposes. Add the following in your :

will handle the deploy and update your submodule version.

A typical workflow would be:

  1. make some changes to your markdown files or
  2. to your source repo
  3. to your GitHub page

Why so complicated ?

Can't I just run and use as my GitHub page?
You can! See the GitHub docs. You will need to commit the build artifacts, or you could even use a different branch for the GitHub page altogether. IMHO I'd much rather track the actual source code and deploy the minimal amount of files in the public project, and having two completely unrelated branches in the same repository is kind of an overly obscure solution. Hence the submodule approach. But that is my biased opinion, use whichever solution works best for you!

Just show me the code

Here is a sample project containing the output of everything described in this post:

Similar articles

Here are a few other articles I could find before writing this post:

Summary

You just created a brand new GitHub page hosting all your desired markdown generated documentation. Which can also contain your cv, portfolio, todo list, random thoughts, cat pictures, etc. you name it. Go nuts, the web is limitless.

Happy hacking!

Sours: https://dev.to/ar2pi/publish-your-markdown-docs-on-github-pages-6pe


412 413 414 415 416