Month: August 2019

  • Create a new public repository on GitHub without using the command line

    Create a new public repository on GitHub without using the command line

    How to create a new Public repository on GitHub so you can:

    • start coding on your development computers.
    • track revisions to your code and restore if needed,
    • share your open source code with the world, or a small team of developers.

    All of this, without using the command line.

    There are lots of great reasons to use GitHub to share a repository of your code, like:

    What you need

    Before you start, be sure that you:

    • Have a GitHub account set up correctly.
    • Know what language you want to use to develop your project.

    Git repositories (also called a “repo”) are easier to manage if you select a single development language.

    Your public repository needs an open source license

    These steps assume that you want to create a public repo, which means that anyone can view your code. This is ideal if you want to release your code as an open source project.

    An open source project must include an open source license. We recommend the MIT License to get started. According to GitHub, the MIT License is:

    A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.

    You may want to select a more restrictive license, like the GPL, but that’s a topic for another post.

    Or, you may want to keep your repository private, in which case you don’t need a license.

    The steps to create a private repository are therefore slightly simpler than the steps described here to create a public repo.

    Create a new public repository on GitHub

    To get started, log into GitHub.

    A sample Create a new repository page for an open source (public) project in Python
    1. In the upper right corner, next to your avatar, click [+] and then select New repository. The Create a new repository page will open.
    2. Name your repository.
    3. Write a short description. This will automatically appear in your new README.md file.
    4. Select Public, since this is an open source project.
    5. Select Initialize this repository with a README.
    6. Recommended – Add .gitignore: select your development language.
    7. Recommended – Add a license: MIT License
    8. Click [Create repository]

    At this point, your new repo contains three files:

    • .gitignore — tells Git to ignore certain files, like temp and cache files, that you don’t want to include in your repo.
    • LICENSE — contains the text of your actual open source license, including your name that you used to set up your GitHub account.
    • README.md — this file is the primary project documentation. Use it to:
      • describe your project,
      • list a version history,
      • keep important developer notes,
      • add links to other resources (like a project wiki and additional documentation).

    Now that your repo has at least one file, you can clone your repo to a local development computer.

    When you clone a repo, you can also create a branch. For more information on how to use branches (especially if you’re coding with others), review Hello World (GitHub Guides).

    Let’s keep it simple for now so you can:

    • start coding right away on your favorite development computer, and
    • use Git to track all the changes you make to your code.

    Clone your new public repository

    After you create a new public repository on GitHub, you need to clone it so you can work with it on your local development computer.

    In addition, you can apply these steps to clone any public repository on GitHub, too — not just repos that you create.

    Cloning a repo means you’re going to create a full copy of all the data in your repo — not just the code, but all of the different versions of the files contained within.

    Cloning a repo also means that you can contribute code back to the repo.

    If you just want to look at code in a repo, and maybe play around with it on your computer, then you can simply download a ZIP of the current state of the code files.

    Downloading a ZIP, however, means you

    • you don’t receive a copy of the version history,
    • it doesn’t allow you to use git to update the repo with your changes.

    Therefore, you want to clone your project so you can use git to:

    • track all the changes you make to your code
    • work with branches
    • collaborate with other developers

    So: clone your new repo to take advantage of all the features git has to offer.

    Select a connection type for your repo

    You can clone a GitHub repository using two types of connections: HTTPS and SSL. Both are secure, encrypted connections.

    HTTPS is easier to use, because:

    • You typically won’t run into a firewall blocking HTTPS connections.
    • You can use the handy GitHub Desktop app to clone your repo — no need to use the command line.

    To learn more about the differences between HTTPS and SSL connections to your GitHub repo, read Which remote URL should I use?.

    Also, you can always change your mind later and switch from HTTPS to SSL. For details, learn how to change a remote repo’s URL and connection type.

    Finally, If you are comfortable working at the command line, or you’d like to understand the specific git commands you need to clone a repo, check out Getting a Git Repository.

    To keep things simple for now, we’ll use the GitHub Desktop app to clone a public GitHub repo.

    Clone your new public repository with GitHub Desktop

    First, download the GitHub Desktop app to your Windows or Mac development computer.

    Note: if you’re using Linux as your development platform, GitHub Desktop isn’t available. But, you can select from a number of other Git GUI Clients.

    If you’ve followed the steps above to create a new public repo, you’ll have your new repo open in your browser.

    If not, just log into GitHub and click the repo name you want to clone to your computer. Or, find any other public repo you want to clone.

    Then, on the repo’s main page:

    1. Click the big green [Clone or download] button.
    2. Select either SSH or HTTPS as your connection protocol. I prefer SSH, but HTTPS is easier to start with (no SSH key required).
    3. Click the [Open in Desktop] link that appears.
    4. Your browser may display a Launch Application window.
    5. The GitHub Desktop app opens and displays the Clone a repository dialog box.
    6. Review the Local Path proposed for your new repo. If you’d like to change it, click [Choose…] and select the folder that you want to contain your new repo. In other words, your new repo will appear as a folder inside of the folder you selected.
    7. Once you’re satisfied, click [Clone].
    Use GitHub Desktop to choose where to store your new public repository on your development computer

    After that, the GitHub Desktop app will display a progress indicator, then the contents of your new repo. You’ll also see some handy buttons to:

    • launch your favorite code editor
    • view the files in the repo on your local computer
    • view your repo on GitHub.com

    Adding files and code to your new public repository on GitHub

    Now that you’ve set up a repo on your local development computer, you can start coding, or add existing files.

    Add existing files

    Use your favorite file management tool (such as the Mac Finder, Windows Explorer, the command line, whatever) to move files into your new repository folder. Then:

    1. open GitHub Desktop,
    2. commit the files to your repo,
    3. (optional) add a comment,
    4. push the changes to your master branch on GitHub.

    Start coding

    If you aren’t already, you should certainly use a code editor with integrated support for Git. This includes some terrific open source editors like MS Visual Studio Code, or Atom.

    So, you don’t have to use the command line to work with your repository, even after you start coding.

    When you open a folder that’s also a clone of a git repo, your code editor will automatically recognize that the folder is a git repo, because of the hidden .git folder contained inside.

    Then, you can fetch, commit, push, and pull your code to your repo branches in your code editor. All of this without having to enter any commands at the command line.

    Photo by Annie Spratt on Unsplash

  • How to improve the readability & SEO of your posts

    If your posts are easy for people to read and understand, they’re also easier for search engines to analyze and rank.

    That means good writing and formatting = great SEO.

    In a sense, search engines look at your page like a human visitor does: they both want to figure out what’s the most relevant information on the page.

    To improve the readability of your posts and improve SEO at the same time, you need to start with good writing.

    Writing Well for Websites

    Start by:

    Writing for clarity and persuasion …

    1. Grab the reader with the first sentence.

    2. Remove unnecessary words.

    3. Keep things simple (write for a grade 8).

    4. Short sentences are better.

    5. Active voice is easier to process than passive.

    A Shane Parrish tweet summarizing Scott Adams’ blog post, The Day You Became A Better Writer from The Dilbert Blog.

    A few more writing tips to make your writing more compelling and accessible:

    • Write short paragraphs comprised of one or two short sentences. This breaks up the text, making it easier to read on screen.
    • Avoid formal or jargon-laden language. Not everyone who comes to your site has a degree in the field. In fact, some people who visit your site may not even be experts! Don’t scare them off with dense language that only makes sense to insiders.
    • Write like you’re explaining something to a friend in a casual conversation. You’re not going to say “therefore, in conclusion…” to someone in conversation, so don’t add that to your web pages, either.
    • It’s better to be passionate and opinionated than “objective.” Let’s be honest, no one is truly objective. Unless you’re writing for a newspaper that insists on giving both sides of a story, make it clear where you stand and what you think. You’ll find this improves your writing, too.
    • Be specific: good writing is concise and detailed. Avoid vague abstractions or broad generalizations. To help your reader understand, give an example.
    • Stay focused on your main idea and topic: Each sentence on your page should explain one idea only, and each page should focus on one topic. If you want to express two separate ideas, use two separate sentences. If you want to explore more than one topic, write more than one post.

    Layout for Web Pages

    The words you write matter, but so does the way you format them on the web page.

    That’s because search engines like Google analyze your web pages to find clues about which words on your page are most important.

    Google uses formatting as one of the factors in determining how relevant a word or phrase is to the content of your page.

    Fortunately, these text formats also make your web page easier to read:

    • Use lots of headings! Headings break up your text and tell a reader where to find the information they’re looking for in your page. Bonus SEO tip: incorporate keywords into your headings).
    • Use bold type to call attention to important words or phrases. Avoid italics, which can be difficult to read on a screen, especially for long passages of text.
    • Use numbered and bulleted lists. Pro tip: highlight the important phrases in each list item to make the list even easier to scan (and easier for Google to analyze).
    • Add graphics and photos with compelling, informative captions and alt text. Everyone loves to look at pictures. A well chosen image can draw attention to a section of your writing, and the image’s caption stands out from the rest of the text. Google thinks that words in captions and the image alt tag are extra relevant, too. Pro tip: search for freely available images covered by a Creative Commons license to find relevant photos and images for your posts.

    Use Hyperlinks

    Hyperlinks to other posts on your site (internal hyperlinks) and to posts on other websites (external or outbound links) improve readability and SEO:

    • Links to other sources that reinforce the ideas in your writing add credibility to your posts.
    • Links to other, related posts in your site help search engines find and analyze related content on your site.
    • Because hyperlinks are colored and formatted differently than other text, they naturally stand out from the rest of the text on a page.
    • If your page contains lots of useful hyperlinks to other relevant web pages related to the subject, visitors will want to save or share the page as a valuable resource.

    Google also looks closely at the words in the hyperlink to evaluate the relevance of your page for search rankings.

    Pro Tip: if your hyperlink points to an external website (an outbound link), set the link to open the external page in a new browser tab.

    Edit your writing

    “Writing and rewriting are a constant search for what it is one is saying.”

    John Updike

    To make your writing clear and persuasive, you need to edit. Make that part of your writing process. Go back and check what you’ve written, looking for ways to pare down excessive verbiage.

    Ask someone else to read what you’ve written, and edit your writing.

    Collaborative writing tools like Google Docs can help with this part of the writing process.

    But, you can also publish a post to your site and then send out links to the new post to ask for feedback.

    You can always go back and improve a web page after you’ve published it.

    Ask your readers for comments, too!

    Use checklists to improve the quality and consistency of your writing

    Refer to this article as a way check through your writing and to ensure you’re doing everything you can to make your post easy to understand and read online.

    You can also use this Essential blog post checklist for WordPress: 7 Steps to improve traffic and SEO, to improve the SEO performance of your posts, even if you aren’t using WordPress.

  • How a WordPress link opens a new browser tab

    Often, you want to edit a page or post so your WordPress link opens a new browser tab.

    If a link in your WordPress site goes to an external URL (not on your WordPress site) you should tell the browser to open a new browser tab. This reinforces the idea that you’re going to a different site, and makes it easier for your site visitor to return to where they left your site

    On the other hand, for internal links (within the same WordPress site) you typically want to use the default behavior, where a new page opens in the same browser tab or window after you click the link.

    WordPress link opens a new tab (Classic editor)

    If you’re using the Classic editor, follow these steps so your WordPress link opens a new browser tab:

    1. Log into your WordPress site.
    2. Open the page or post you want to edit in your favorite browser.
    3. Click on the Edit Post (or Page) link on the WordPress Toolbar. The Edit Post screen will display the editor.
    4. In the editor, hover over the link you want to edit.
    5. In the link editing popup that appears below the link, click the Edit pencil icon.
    6. Click the Link options gear icon.
    7. Check Open link in a new tab
    8. Click Update

    When you’re done editing the post, click [Update] in the Edit Post Publish box.

    Then click View post at the top of the Edit Post page to check your work.