Github Html Readme

Posted on  by admin

If you’re a developer and anything like the people here at Delicious Brains, you’ve likely got a whole bunch of open source repositories on GitHub, some of which you want. Publii includes support for Github Pages, which provide a space for you to build a website that you can use for highlighting your Github projects. GitHub의 새로운 프로필 페이지 README 기능은 개발자 인터넷의 Myspace 페이지에 약간의 개성을 가져다줍니다. Markdown은 표준 정적 텍스트 콘텐츠에 가장 적합하지만 창의적인 사람들이 다음 수준의 README를 만드는 작업을 중단하지는 않습니다. GIF와 이미지를 포함하여 움직임과 화려 함을 추가 할 수 있지만 (GitHub. Get to know why writing a good README is important, and how to improve its legibility. The Official Tutorial Archive™ of Nokogiri®.

In this tutorial we will look at how to create a github style markdown editor with preview button. Github’s markdown editor is used to edit the README.md file. This file contains getting started information about the github repository.

Using EpicEditor

EpicEditor is a JavaScript Library which can embed a mardown editor in an webpage. In this tutorial we will build a Github style markdown tool using EpicEditor.

Download EpicEditor and place it in your demo project. This is how my demo project looks

Github readme html code
--github-markdown
-index.html
--epiceditor
--themes
--preview
-preview-dark.css
-github.css
-bartik.css
--editor
-epic-dark.css
-epic-light.css
--base
-epiceditor.css
--js
-epiceditor.min.js
-epiceditor.js

Create a Sample Editor

Here is the code for a sample markdown editor like Github style. With just 62 lines of code we created a editor like github’s.

<!doctype html>
<html>
<head>
<title>Github Style Markdown Editing Preview</title>
<scripttype='text/javascript'src='epiceditor/js/epiceditor.min.js'></script>
</head>
<body>
<buttononclick='preview();'>Preview</button>
<buttononclick='edit();'>Edit</button>
<divid='epiceditor'style='width: 600px; height: 600px; border: 2px solid black'></div>
<br>
<buttononclick='commit();'>Commit Change to Server</button>
<scripttype='text/javascript'>
var opts = {
container: 'epiceditor',
theme: {
base: '/themes/base/epiceditor.css',
editor: '/themes/editor/epic-light.css'
},
clientSideStorage: true,
file: {
name: 'README.md', //name of local file to open. Its not a real file but just localStorage item.
autoSave: 100 //saves the editor data into the local file every 100ms.
},
button: {
preview: false,
fullscreen: false,
bar: false
}
};
var editor = new EpicEditor(opts);
editor.load();
editor.importFile('README.md','#Last Commited Content'); //load file data from server for the last commit.
editor.preview();
function commit()
{
var theContent_html = editor.exportFile('README.md', 'html');
var theContent_md = editor.exportFile('README.md', 'text');
alert(theContent_md);
alert(theContent_html);
//here send data to server to update the file on server side.
}
function preview()
{
editor.preview();
}
function edit()
{
editor.edit();
}
</script>
</body>
</html>

Most of the code above is self explanatory.

A editor represents one file at a time. A file name (here it is README.md) is assigned to the editor. The markdown is stored/updated locally every 100ms. When user clicks the commit button you can retrieve the markdown of the file and send to server.

Whenever page is loaded you can retrieve the markdown of the file from server and load it into the local file using importFile function. Now the editor will show the server version of the file.

In the previous lesson, we created a README.md file. And Github turned it into a webpage, technically.

But it’s just a quickie-homepage for our repo, with a URL that looks like any regular normal file (which, well, it is…):

github.com/username/username.github.io/README.md

Github provides a web publishing service called Github Pages. In this lesson, we will learn how to publish a proper webpage via Github Pages.

According to the Github Pages documentation, by creating a repo named username.github.io, Github Pages knows (by convention) to publish anything in this repo to the corresponding URL:

However, if you visit that URL, you’ll find a 404 page.

Create index.html

Go back to your repository homepage on github.com, e.g.

github.com/username/username.github.io

To the right of the repo name is a little paper-plus icon. Click on it to create a new file.

This will take you to the Github file editor. This time, you’ll have to specify a filename.

Name your filename: index.html

Then type in some plain-text nonsense, e.g.:

Commit the index.html file. You can add a commit message if you wish.

After the commit, you should be taken to your repo file listing, which should now contain two files:

  • README.md
  • index.html

The README file should be unchanged because you didn’t touch the README.md

So what changed? Believe it or not, you’ve published your own webpage.

As per the Github Pages convention, your new webpage exists at:

https://username.github.io

And if you visit that address, you should see a very unimpressive page.

Behold, your new webpage (index.html) on Github Pages:

Not only is your homepage undecorated, but it lacks even the basic spacing between lines. If you View Source (either by right-clicking on the page, or by going to the View > Developer > View Source ) to see the index.html source code, you’ll seeexactly what you entered into the Github file editor.

And yet your browser renders it all as a single line. If you don’t know anything about web development, this is the explanation: the text you entered into index.html wasn’t actual HTML code. It was just, well, plain text. And Github Pages, unlike most blogging and content sites, did nothing to help you with that.

The raw source (i.e. the plaintext) behind index.html:

Web Publishing 101

If you’ve ever written a webpage from scratch, i.e. from the <html> to the closing </body> tag, you might already know the concepts (and can skip ahead). But if your Web publishing experience has been confined to posting in an “update status” box, or through your company’s content-management system, or even on your own WordPress/Tumblr, then what you’ve just done with Github Pages should seem very underwhelming.

And that’s OK. It’s underwhelming because Github Pages merely took the simple text you wrote:

– and put it on a public web server, as is.

So Github Pages basically did nothing here. It “published” your index.html page, if plopping it raw onto the Internet counts as “published.”

(Again, if you have any experience with web development, you should probably skip this section).

Go back to your Github.com repo page (not your Github Pages homepage) and examine the plaintext behind README.md

Now View Source of the rendered README.md (which, again, is visible by default on your Github.com repo page).

Notice how Github turned the plaintext behind README.md into actual HTML code; hence, why the headers and link text are properly formatted.

To get a proper webpage, with real HTML and all that, we’re going to have to write actual HTML ourselves.

In your repo page and file-listing, click through index.html and click the Edit button, which will let you edit index.html via the Github file editor.

Delete all the plaintext in index.html and replace it with some HTML. Such as:

Commit your changes. These should go into effect near-instantaneously, but feel free to take a couple-minutes break.

Then revisit your Github Pages homepage, e.g.

http://username.github.io

Pretty plain, but at least it’s a bonafide webpage; notice those properly-formatted h1 and h2 header tags.

Web publishing, with ease and brevity

So why even use Github Pages, especially if you have no intention of becoming a web developer or even learning basic HTML?

Good question. The simple answer is: In web publishing, as in basically every life choice, you have a tradeoff between:

  1. Power and control
  2. Ease and brevity

Github Pages sits more on the power-and-control-side of the spectrum. If you want to put something on the Web, Github Pages lets you do it from your web browser, rather than the traditional route of setting up your own FTP/Apache server (and by using Github Pages, you’re trading the power and control you have by setting up your own web server).

With a service such as WordPress, you get the ease of creating web content with a rich-text editor, similar to a traditional word-processor.

When you hit Publish Post, WordPress takes care of wrapping your post content in HTML code and putting it in a reasonably pretty container. The tradeoff is that you can’t (easily) break out of those boundaries, not with out learning enough code to hack around WordPress.

It took me about five minutes to create a new blog on WordPress.com, pick a pre-built theme (ThemeTrust’s “McKinley”), and create a new post, with a headline, text, link, blockquote, and even some tags.

WordPress helpfully formats my post and fits it inside the pretty McKinley theme I’ve chosen. Check out the live version and notice all the niceties that WordPress adds, such as making “Albert Einstein” a clickable link. And notice the extras: the tags are also clickable-links, a date has been added to the post, there are Share this: social buttons, and ooh, a courteous notice that my post might show ads, because I am, after all, using WordPress’s free service.

If you want, you can go back to your Github.com repo page and create a new file, like: blog-post.html, and add the same content that I’ve added to my WordPress post.

Commit the new blog-post.html file, which will be auto-published by Github Pages, and visit it at:

username.github.io/blog-post.html

And again, Github Pages does basically nothing.

Web publishing, with power and control

But sometimes nothing can be a pretty cool hand…as in, being handed the reins to create and publish content exactly as you need it to be.

Visit the Wikipedia page for GIF:

Github Html Readme

View Source of the Wikipedia entry on GIF, and then Select All the code and Copy it to your clipboard (i.e. via Ctrl-C or Cmd-C)

Github Html Readme

If you have a WordPress blog, you can follow along as I try to paste this massive chunk of HTML code into the WordPress post editor (in the raw Text mode, not the Visual mode)

Some of the raw HTML is interpreted correctly, but we lose all of the styling of Wikipedia. And for much of the HTML code, WordPress just basically barfs it out as raw text.

Github Readme Html Code

By having a user-friendly interface, WordPress necessarily has to make assumptions about what users often mistakenly copy-and-paste, and these assumptions end up being restrictions, to some degree.

You can see the attempted raw-Wikipedia-HTML-as-WordPress-blog-post on my sample blog.

Now copy-and-paste that same raw Wikipedia HTML into a new file in your Github repo, e.g. wiki-gif.html.

Commit the new wiki-gif.html to your repo.

Wait a second for Github Pages to auto-publish that page and visit it at the expected URL:

http://username.github.io/wiki-gif.html

The two pages are identical, from the content, to Wikipedia’s exact styling, even down to the revolving-GIF.

Things we’ve learned

How to publish to Github Pages

Github Pages is a service run by Github that, when properly configured, will auto-publish the contents of your repo onto the Internet.

To get Github Pages to work for you, if your username is your_username, then you must create a repo named your_username.github.io.

After about 10 minutes, you can expect your content to be on the Web at the URL: http://your_username.github.io

Going forward, I will refer to this as your portfolio homepage/website

Github Readme Html Style

Note: When I refer to the Github repo homepage for your portfolio, I mean the URL of the actual Github repo, e.g.:

Github Readme Html Link

https://github.com/your_username/your_username.github.io

The basic structure of a website

TK

How plaintext is different from raw HTML

Github Profile Readme Html

TK