I am writing a readme for my github project in the .md format. Is there a way can I test what my readme.md file will look like before committing to github?
Github – How to test what the readme.md file will look like before committing to github
githubgithub-flavored-markdownmarkdown
Related Solutions
With Git version 1.7.9 and later
Since Git 1.7.9 (released in late January 2012), there is a neat mechanism in Git to avoid having to type your password all the time for HTTP / HTTPS, called credential helpers. (Thanks to dazonic for pointing out this new feature in the comments below.)
With Git 1.7.9 or later, you can just use one of the following credential helpers:
git config --global credential.helper cache
The credential.helper cache value tells Git to keep your password cached in memory for a particular amount of minutes. The default is 15 minutes, you can set a longer timeout with:
git config --global credential.helper "cache --timeout=3600"
Which sets the cache for 1 hour, or:
git config --global credential.helper "cache --timeout=86400"
For 1 day. You can also store your credentials permanently if so desired, see the other answers below.
GitHub's help also suggests that if you're on Mac OS X and used Homebrew to install Git, you can use the native Mac OS X keystore with:
git config --global credential.helper osxkeychain
For Windows, there is a helper called Git Credential Manager for Windows or wincred in msysgit.
git config --global credential.helper wincred # obsolete
With Git for Windows 2.7.3+ (March 2016):
git config --global credential.helper manager
For Linux, you would use (in 2011) gnome-keyring
(or other keyring implementation such as KWallet).
Nowadays (2020), that would be (on Linux)
Fedora
sudo dnf install git-credential-libsecret
git config --global credential.helper /usr/libexec/git-core/git-credential-libsecret
Ubuntu
sudo apt-get install libsecret-1-0 libsecret-1-dev
cd /usr/share/doc/git/contrib/credential/libsecret
sudo make
git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret
With Git versions before 1.7.9
With versions of Git before 1.7.9, this more secure option is not available, and you'll need to change the URL that your origin
remote uses to include the password in this fashion:
https://you:password@github.com/you/example.git
... in other words with :password
after the username and before the @
.
You can set a new URL for your origin
remote with:
git config remote.origin.url https://you:password@github.com/you/example.git
Make sure that you use https
, and you should be aware that if you do this, your GitHub password will be stored in plaintext in your .git
directory, which is obviously undesirable.
With any Git version (well, since version 0.99)
An alternative approach is to put your username and password in your ~/.netrc
file, although, as with keeping the password in the remote URL, this means that your password will be stored on the disk in plain text and is thus less secure and not recommended. However, if you want to take this approach, add the following line to your ~/.netrc
:
machine <hostname> login <username> password <password>
... replacing <hostname>
with the server's hostname, and <username>
and <password>
with your username and password. Also remember to set restrictive file system permissions on that file:
chmod 600 ~/.netrc
Note that on Windows, this file should be called _netrc
, and you may need to define the %HOME% environment variable - for more details see:
Markdown is a plain-text file format. The extensions .md
and .markdown
are just text files written in Markdown syntax. If you have a Readme.md
in your repo, GitHub will show the contents on the home page of your repo. Read the documentation:
You can edit the Readme.md
file in GitHub itself. Click on Readme.md, you will find an edit button. You can preview your changes and even commit them from there.
Since it is a text file, Notepad or Notepad++ (Windows), TextEdit (Mac) or any other text editor can be used to edit and modify it. Specialized editors exist that automatically parse the markdown as you type it and generate a preview, while others apply various syntax coloring and decorations to the displayed text. In both cases though, the saved file is still a readable text file.
If you want to create an md
file with preview and if you prefer not to install any special editors, you can use online editors like dillinger.io and stackedit.io. They provide live preview. You can also export your files to Google Drive or Dropbox.
Related Topic
- Git – Download a single folder or directory from a GitHub repo
- GitHub relative link in Markdown file
- Github – the difference between README and README.md in GitHub projects
- Github – How to add images to README.md on GitHub
- Changing image size in Markdown
- GitHub satanically messing with Markdown – changes 666 to DCLXVI
Best Answer
Many ways: If you're on a Mac, use Mou.
If you want to test in a browser, you could try StackEdit, as pointed out by @Aaron or Dillinger since Notepag seems to be down now. Personally I use Dillinger since it just works and saves all my documents in my browser's local database.